passenger 4.0.5 → 4.0.6
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.
- data.tar.gz.asc +7 -7
- data/.travis.yml +1 -2
- data/CONTRIBUTING.md +20 -5
- data/CONTRIBUTORS +67 -0
- data/LICENSE +1 -1
- data/NEWS +48 -0
- data/Rakefile +2 -2
- data/bin/passenger-config +18 -0
- data/bin/passenger-install-apache2-module +2 -0
- data/bin/passenger-install-nginx-module +11 -12
- data/bin/passenger-memory-stats +2 -0
- data/bin/passenger-status +152 -69
- data/build/agents.rb +1 -5
- data/build/basics.rb +26 -13
- data/build/cplusplus_support.rb +9 -0
- data/build/debian.rb +129 -0
- data/build/documentation.rb +6 -2
- data/build/integration_tests.rb +13 -2
- data/build/misc.rb +16 -0
- data/build/packaging.rb +67 -51
- data/build/preprocessor.rb +314 -0
- data/build/test_basics.rb +1 -0
- data/{debian → debian.template}/README.Debian +0 -0
- data/{debian → debian.template}/changelog +131 -0
- data/debian.template/compat +1 -0
- data/debian.template/control +71 -0
- data/debian.template/copyright +385 -0
- data/debian.template/libapache2-mod-passenger.install +3 -0
- data/{debian → debian.template}/libapache2-mod-passenger.postinst +0 -0
- data/{debian → debian.template}/libapache2-mod-passenger.prerm +0 -0
- data/debian.template/locations.ini +12 -0
- data/debian.template/passenger.conf +4 -0
- data/{debian → debian.template}/passenger.load +0 -0
- data/debian.template/patches/series +0 -0
- data/debian.template/repack.sh +42 -0
- data/debian.template/ruby-passenger-dev.install +3 -0
- data/debian.template/ruby-passenger-doc.install +2 -0
- data/debian.template/ruby-passenger.docs +4 -0
- data/debian.template/ruby-passenger.install +11 -0
- data/debian.template/ruby-passenger.manpages +4 -0
- data/debian.template/rules.template +35 -0
- data/debian.template/source/format +1 -0
- data/debian.template/watch +3 -0
- data/dev/run_travis.sh +46 -46
- data/doc/Architectural overview.html +2 -2
- data/doc/Packaging.html +27 -18
- data/doc/Packaging.txt.md +27 -18
- data/doc/Security of user switching support.html +2 -2
- data/doc/Users guide Apache.html +881 -95
- data/doc/Users guide Apache.idmap.txt +48 -6
- data/doc/Users guide Apache.txt +13 -1
- data/doc/Users guide Nginx.html +1063 -190
- data/doc/Users guide Nginx.idmap.txt +89 -45
- data/doc/Users guide Nginx.txt +45 -0
- data/doc/Users guide Standalone.html +7 -7
- data/doc/users_guide_snippets/alternative_for_flying_passenger.txt +1 -0
- data/doc/users_guide_snippets/environment_variables.txt +221 -0
- data/doc/users_guide_snippets/installation.txt +66 -17
- data/doc/users_guide_snippets/support_information.txt +3 -3
- data/doc/users_guide_snippets/tips.txt +352 -40
- data/ext/common/Account.h +4 -3
- data/ext/common/AccountsDatabase.h +6 -6
- data/ext/common/AgentsStarter.h +1 -13
- data/ext/common/ApplicationPool2/DirectSpawner.h +4 -4
- data/ext/common/ApplicationPool2/DummySpawner.h +1 -1
- data/ext/common/ApplicationPool2/Group.h +9 -4
- data/ext/common/ApplicationPool2/Implementation.cpp +6 -1
- data/ext/common/ApplicationPool2/Options.h +65 -37
- data/ext/common/ApplicationPool2/Pool.h +91 -41
- data/ext/common/ApplicationPool2/Process.h +6 -6
- data/ext/common/ApplicationPool2/SmartSpawner.h +14 -14
- data/ext/common/ApplicationPool2/Socket.h +1 -1
- data/ext/common/ApplicationPool2/Spawner.h +24 -16
- data/ext/common/ApplicationPool2/SpawnerFactory.h +9 -1
- data/ext/common/ApplicationPool2/SuperGroup.h +1 -1
- data/ext/common/Constants.h +1 -1
- data/ext/common/Logging.cpp +12 -7
- data/ext/common/MessageServer.h +7 -12
- data/ext/common/MultiLibeio.cpp +5 -5
- data/ext/common/ResourceLocator.h +2 -6
- data/ext/common/ServerInstanceDir.h +37 -10
- data/ext/common/UnionStation.h +10 -10
- data/ext/common/Utils.cpp +30 -4
- data/ext/common/Utils.h +7 -0
- data/ext/common/Utils/BlockingQueue.h +2 -2
- data/ext/common/Utils/Lock.h +2 -2
- data/ext/common/Utils/MessagePassing.h +2 -2
- data/ext/common/Utils/Timer.h +4 -4
- data/ext/common/agents/HelperAgent/AgentOptions.h +2 -0
- data/ext/common/agents/HelperAgent/Main.cpp +57 -16
- data/ext/common/agents/HelperAgent/RequestHandler.h +4 -1
- data/ext/common/agents/LoggingAgent/AdminController.h +91 -0
- data/ext/common/agents/LoggingAgent/LoggingServer.h +46 -29
- data/ext/common/agents/LoggingAgent/Main.cpp +43 -16
- data/ext/common/agents/LoggingAgent/RemoteSender.h +7 -7
- data/ext/common/agents/Watchdog/AgentWatcher.cpp +11 -11
- data/ext/common/agents/Watchdog/LoggingAgentWatcher.cpp +3 -1
- data/ext/common/agents/Watchdog/Main.cpp +62 -0
- data/ext/libeio/config.guess +206 -167
- data/ext/libeio/config.sub +142 -68
- data/ext/libev/config.guess +304 -290
- data/ext/libev/config.sub +198 -77
- data/ext/nginx/config +4 -0
- data/ext/nginx/ngx_http_passenger_module.c +1 -0
- data/ext/oxt/implementation.cpp +4 -4
- data/lib/phusion_passenger.rb +14 -5
- data/lib/phusion_passenger/abstract_installer.rb +41 -0
- data/lib/phusion_passenger/admin_tools/server_instance.rb +48 -39
- data/lib/phusion_passenger/message_client.rb +31 -7
- data/lib/phusion_passenger/native_support.rb +35 -12
- data/lib/phusion_passenger/packaging.rb +16 -2
- data/lib/phusion_passenger/platform_info/binary_compatibility.rb +6 -31
- data/lib/phusion_passenger/platform_info/operating_system.rb +1 -1
- data/lib/phusion_passenger/preloader_shared_helpers.rb +3 -1
- data/lib/phusion_passenger/request_handler.rb +1 -1
- data/lib/phusion_passenger/standalone/command.rb +6 -6
- data/lib/phusion_passenger/standalone/main.rb +23 -8
- data/lib/phusion_passenger/standalone/package_runtime_command.rb +9 -5
- data/lib/phusion_passenger/standalone/runtime_installer.rb +9 -10
- data/lib/phusion_passenger/standalone/start_command.rb +20 -4
- data/resources/templates/installer_common/freebsd9_broken_cxx_runtime.txt.erb +19 -0
- data/resources/templates/installer_common/low_amount_of_memory_warning.txt.erb +22 -0
- data/resources/templates/standalone/config.erb +3 -2
- data/test/cxx/ApplicationPool2/DirectSpawnerTest.cpp +4 -4
- data/test/cxx/ApplicationPool2/PoolTest.cpp +1 -1
- data/test/cxx/ApplicationPool2/SmartSpawnerTest.cpp +7 -7
- data/test/cxx/ApplicationPool2/SpawnerTestCases.cpp +9 -9
- data/test/cxx/EventedBufferedInputTest.cpp +17 -17
- data/test/cxx/RequestHandlerTest.cpp +5 -5
- data/test/cxx/ServerInstanceDirTest.cpp +3 -1
- data/test/cxx/TestSupport.h +4 -4
- data/test/cxx/UnionStationTest.cpp +3 -1
- data/test/cxx/UtilsTest.cpp +2 -0
- data/test/integration_tests/apache2_tests.rb +2 -2
- data/test/integration_tests/native_packaging_spec.rb +170 -0
- data/test/ruby/spec_helper.rb +0 -1
- data/test/stub/apache2/httpd.conf.erb +1 -1
- data/test/stub/nginx/nginx.conf.erb +1 -0
- data/test/support/apache2_controller.rb +1 -1
- data/test/support/placebo-preloader.rb +1 -1
- data/test/support/test_helper.rb +5 -2
- metadata +32 -26
- metadata.gz.asc +7 -7
- data/debian/compat +0 -1
- data/debian/control +0 -49
- data/debian/copyright +0 -20
- data/debian/libapache2-mod-passenger.install +0 -1
- data/debian/passenger-common.install +0 -4
- data/debian/passenger.conf +0 -4
- data/debian/prerm +0 -2
- data/debian/rules +0 -37
- data/debian/watch +0 -3
- data/dev/googlecode_upload.py +0 -265
- data/ext/common/agents/HelperAgent/BacktracesServer.h +0 -60
- data/resources/templates/nginx/not_available_when_natively_packaged.txt.erb +0 -8
- data/test/stub/rails3.1/app/assets/javascripts/application.js +0 -9
- data/test/stub/rails3.2/app/assets/javascripts/application.js +0 -15
- data/test/stub/rails_apps/2.3/mycook/public/javascripts/application.js +0 -2
- data/test/stub/rails_apps/2.3/mycook/public/javascripts/controls.js +0 -963
- data/test/stub/rails_apps/2.3/mycook/public/javascripts/dragdrop.js +0 -973
- data/test/stub/rails_apps/2.3/mycook/public/javascripts/effects.js +0 -1128
- data/test/stub/rails_apps/2.3/mycook/public/javascripts/prototype.js +0 -4320
@@ -167,9 +167,25 @@ passenger-install-nginx-module
|
|
167
167
|
At some point it will ask you which prefix to install Nginx to. If you're upgrading, then specify the same prefix that you used last time, as well as the same configuration parameters that you used last time.
|
168
168
|
endif::[]
|
169
169
|
|
170
|
+
[float]
|
171
|
+
==== Step 6: Restarting the Flying Passenger daemon
|
172
|
+
|
173
|
+
If you are using <<flying_passenger,Flying Passenger>> then you must restart the Flying Passenger daemon by sending it the SIGTERM signal:
|
174
|
+
|
175
|
+
-------------------------------
|
176
|
+
kill `cat /path-to/flying-passenger.pid`
|
177
|
+
-------------------------------
|
178
|
+
|
179
|
+
Or, if Flying Passenger is not running with a PID file, look up its PID us `ps` and then send it SIGTERM:
|
180
|
+
|
181
|
+
-------------------------------
|
182
|
+
ps auxw | grep flying-passenger
|
183
|
+
kill PID_OF_FLYING_PASSENGER
|
184
|
+
-------------------------------
|
185
|
+
|
170
186
|
[[verify_passenger_running]]
|
171
187
|
[float]
|
172
|
-
==== Step
|
188
|
+
==== Step 7: Verifying that Phusion Passenger is running
|
173
189
|
|
174
190
|
Restart your web server and run:
|
175
191
|
|
@@ -191,11 +207,7 @@ If the output is not as expected, then please refer to the <<troubleshooting,Tro
|
|
191
207
|
[float]
|
192
208
|
==== Step 1: download and extract the tarball
|
193
209
|
|
194
|
-
Download the open source Phusion Passenger tarball from link:https://www.phusionpassenger.com/download#open_source[the Phusion Passenger website].
|
195
|
-
|
196
|
-
* All versions starting from 4.0.0 can be found on link:https://code.google.com/p/phusion-passenger/downloads/list[Google Code].
|
197
|
-
* All versions prior to 4.0.0, except for beta releases and Release Candidates, can be found on link:http://rubyforge.org/frs/?group_id=5873&release_id=46919[RubyForge].
|
198
|
-
* All beta releases and Release Candidates prior to 4.0.0 beta 1 can be found on link:https://code.google.com/p/phusion-passenger/downloads/list[Google Code].
|
210
|
+
Download the open source Phusion Passenger tarball from link:https://www.phusionpassenger.com/download#open_source[the Phusion Passenger website]. Older versions can be found on link:https://www.phusionpassenger.com/file_releases[the release archive].
|
199
211
|
|
200
212
|
If you a link:https://www.phusionpassenger.com/enterprise[Phusion Passenger Enterprise] customer, download the Phusion Passenger Enterprise tarball from the link:https://www.phusionpassenger.com/orders[Customer Area]. Also be sure to download the *license key* and save it as '/etc/passenger-enterprise-license'.
|
201
213
|
|
@@ -309,11 +321,28 @@ Note that the `passenger-install-nginx-module` command is inside the 'bin' subdi
|
|
309
321
|
endif::[]
|
310
322
|
|
311
323
|
[float]
|
312
|
-
==== Step 6:
|
324
|
+
==== Step 6: Restarting the Flying Passenger daemon
|
325
|
+
|
326
|
+
If you are using <<flying_passenger,Flying Passenger>> then you must restart the Flying Passenger daemon by sending it the SIGTERM signal:
|
327
|
+
|
328
|
+
-------------------------------
|
329
|
+
kill `cat /path-to/flying-passenger.pid`
|
330
|
+
-------------------------------
|
331
|
+
|
332
|
+
Or, if Flying Passenger is not running with a PID file, look up its PID us `ps` and then send it SIGTERM:
|
333
|
+
|
334
|
+
-------------------------------
|
335
|
+
ps auxw | grep flying-passenger
|
336
|
+
kill PID_OF_FLYING_PASSENGER
|
337
|
+
-------------------------------
|
338
|
+
|
339
|
+
[float]
|
340
|
+
==== Step 7: Verifying that Phusion Passenger is running
|
313
341
|
|
314
342
|
Please refer to <<verify_passenger_running,this section>>. Note that all Phusion Passenger administration scripts are located inside the 'bin' subdirectory of the Phusion Passenger source directory, so you would have to run something like '/opt/passenger/passenger-x.x.x/bin/passenger-memory-stats'.
|
315
343
|
|
316
344
|
|
345
|
+
[[install_on_debian_ubuntu]]
|
317
346
|
=== Installing or upgrading on Debian 6 or Ubuntu
|
318
347
|
|
319
348
|
John Leach from Brightbox has kindly provided Ubuntu packages for Phusion Passenger. The Ubuntu Lucid packages are compatible with Debian 6. The packages are available from the link:http://wiki.brightbox.co.uk/docs:phusion-passenger[Brightbox repository]. Only packages for the open source version of Phusion Passenger are provided. link:https://www.phusionpassenger.com/enterprise[Phusion Passenger Enterprise] customers should use the <<rubygems_generic_install,generic RubyGems installation method>> or <<tarball_generic_install,the generic tarball installation method>> instead.
|
@@ -325,7 +354,7 @@ If you use these packages to install Phusion Passenger then you do not need to r
|
|
325
354
|
On Ubuntu versions newer than 8.04 Hardy, register the Brightbox Apache PPA as follows:
|
326
355
|
|
327
356
|
-----------------------------
|
328
|
-
sudo apt-add-repository ppa:brightbox/passenger
|
357
|
+
sudo apt-add-repository ppa:brightbox/passenger-experimental
|
329
358
|
sudo apt-get update
|
330
359
|
-----------------------------
|
331
360
|
|
@@ -334,7 +363,7 @@ On Ubuntu 8.04 Hardy and on Debian, the `apt-add-repository` command isn't avail
|
|
334
363
|
Debian 6:
|
335
364
|
|
336
365
|
-----------------------------
|
337
|
-
sudo sh -c 'echo "deb http://ppa.launchpad.net/brightbox/passenger/ubuntu lucid main" > /etc/apt/sources.list.d/brightbox-passenger.list'
|
366
|
+
sudo sh -c 'echo "deb http://ppa.launchpad.net/brightbox/passenger-experimental/ubuntu lucid main" > /etc/apt/sources.list.d/brightbox-passenger.list'
|
338
367
|
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C3173AA6
|
339
368
|
sudo apt-get update
|
340
369
|
-----------------------------
|
@@ -342,7 +371,7 @@ sudo apt-get update
|
|
342
371
|
Ubuntu 8.04 Hardy:
|
343
372
|
|
344
373
|
-----------------------------
|
345
|
-
sudo sh -c 'echo "deb http://ppa.launchpad.net/brightbox/passenger/ubuntu hardy main" > /etc/apt/sources.list.d/brightbox-passenger.list'
|
374
|
+
sudo sh -c 'echo "deb http://ppa.launchpad.net/brightbox/passenger-experimental/ubuntu hardy main" > /etc/apt/sources.list.d/brightbox-passenger.list'
|
346
375
|
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C3173AA6
|
347
376
|
sudo apt-get update
|
348
377
|
-----------------------------
|
@@ -360,7 +389,7 @@ The Apache package provides configuration snippets for you, so you don't need to
|
|
360
389
|
On Ubuntu versions newer than 8.04 Hardy, register the Brightbox Apache PPA as follows:
|
361
390
|
|
362
391
|
-----------------------------
|
363
|
-
sudo apt-add-repository ppa:brightbox/passenger-
|
392
|
+
sudo apt-add-repository ppa:brightbox/passenger-experimental
|
364
393
|
sudo apt-get update
|
365
394
|
-----------------------------
|
366
395
|
|
@@ -369,7 +398,7 @@ On Ubuntu 8.04 Hardy and on Debian, the `apt-add-repository` command isn't avail
|
|
369
398
|
Debian 6:
|
370
399
|
|
371
400
|
-----------------------------
|
372
|
-
sudo sh -c 'echo "deb http://ppa.launchpad.net/brightbox/passenger-
|
401
|
+
sudo sh -c 'echo "deb http://ppa.launchpad.net/brightbox/passenger-experimental/ubuntu lucid main" > /etc/apt/sources.list.d/brightbox-passenger-nginx.list'
|
373
402
|
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C3173AA6
|
374
403
|
sudo apt-get update
|
375
404
|
-----------------------------
|
@@ -377,7 +406,7 @@ sudo apt-get update
|
|
377
406
|
Ubuntu 8.04 Hardy:
|
378
407
|
|
379
408
|
-----------------------------
|
380
|
-
sudo sh -c 'echo "deb http://ppa.launchpad.net/brightbox/passenger/ubuntu hardy main" > /etc/apt/sources.list.d/brightbox-passenger-nginx.list'
|
409
|
+
sudo sh -c 'echo "deb http://ppa.launchpad.net/brightbox/passenger-experimental/ubuntu hardy main" > /etc/apt/sources.list.d/brightbox-passenger-nginx.list'
|
381
410
|
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C3173AA6
|
382
411
|
sudo apt-get update
|
383
412
|
-----------------------------
|
@@ -598,17 +627,22 @@ endif::[]
|
|
598
627
|
|
599
628
|
=== Customizing the compilation process
|
600
629
|
|
630
|
+
The Phusion Passenger compilation process can be customized with environment variables. You can learn more about environment variables in <<about_environment_variables,About environment variables>>.
|
631
|
+
|
601
632
|
==== Setting the compiler
|
602
633
|
|
603
634
|
You can force the Phusion Passenger build system to use a specific C or C++ compiler by setting the `CC` and `CXX` environment variables. These may be set to any arbitrary shell commands.
|
604
635
|
|
605
636
|
For example, contributors who want to hack on Phusion Passenger may want to use Clang for faster compilation and link:http://ccache.samba.org/[ccache] for faster recompilation, and may want to enable more error-catching compilation flags:
|
606
637
|
|
638
|
+
[source,sh]
|
607
639
|
----------------------
|
608
640
|
export CC='ccache clang -fcolor-diagnostics -Qunused-arguments -fcatch-undefined-behavior -ftrapv'
|
609
641
|
export CXX='ccache clang++ -fcolor-diagnostics -Qunused-arguments -fcatch-undefined-behavior -ftrapv'
|
610
642
|
----------------------
|
611
643
|
|
644
|
+
NOTE: If you run the installer with `sudo` then environment variables may not be passed properly. Learn more at <<env_vars_and_sudo,Environment variables and sudo>>.
|
645
|
+
|
612
646
|
==== Adding additional compiler or linker flags
|
613
647
|
|
614
648
|
On some systems, C/C++ libraries and headers that Phusion Passenger requires may be located in a non-standard directory. You can force the Phusion Passenger build system to look in those locations by injecting compiler and linker flags using the following environment variables:
|
@@ -626,16 +660,29 @@ On some systems, C/C++ libraries and headers that Phusion Passenger requires may
|
|
626
660
|
`EXTRA_LDFLAGS`::
|
627
661
|
Similar to `EXTRA_PRE_LDFLAGS`, but injected at the very end of the command string, even after `EXTRA_CFLAGS` and `EXTRA_CXXFLAGS`.
|
628
662
|
|
629
|
-
|
663
|
+
NOTE: If you run the installer with `sudo` then environment variables may not be passed properly. Learn more at <<env_vars_and_sudo,Environment variables and sudo>>.
|
664
|
+
|
665
|
+
==== Forcing location of command line tools and dependencies
|
630
666
|
|
631
667
|
The Phusion Passenger build system attempts to autodetect many things by locating relevant helper tools. For example, to find out which compiler flags it should use for compiling Apache modules, it locates the `apxs2` command and queries it. To find out which compiler flags it should use for libcurl, it queries the `curl-config` command. These commands may not be in `$PATH`, or even when they are you may want to use a different one.
|
632
668
|
|
633
|
-
You can
|
669
|
+
You can force the build to find certain command line tools at certain locations by using the following environment variables:
|
634
670
|
|
635
671
|
`HTTPD`::
|
636
672
|
The location of the `httpd` executable (the Apache server executable).
|
637
673
|
`APXS2`::
|
638
|
-
The location of the `apxs2` executable (the Apache module developer tool).
|
674
|
+
The location of the `apxs2` executable (the Apache module developer tool). Only used by `passenger-install-apache2-module`.
|
675
|
+
+
|
676
|
+
This environment variable, together with `HTTPD`, are what you need to customize if you have multiple Apache installations on your system, or if your Apache is located in a non-standard location which Phusion Passenger cannot detect. By setting `APXS2` and `HTTP` to the right paths, you can force Phusion Passenger to be compiled against that specific Apache installation.
|
677
|
+
+
|
678
|
+
For example, if your Apache installation is located in `/opt/lamp/apache2`, then you can run the installer as follows:
|
679
|
+
+
|
680
|
+
---------------------------------------
|
681
|
+
$ sudo bash
|
682
|
+
# export HTTPD=/opt/lampp/apache2/bin/apache
|
683
|
+
# export APXS2=/opt/lampp/apache2/bin/apxs
|
684
|
+
# passenger-install-apache2-module
|
685
|
+
---------------------------------------
|
639
686
|
`APR_CONFIG`::
|
640
687
|
The location of the `apr-config` executable (the Apache Portable Runtime developer tool).
|
641
688
|
`APU_CONFIG`::
|
@@ -645,6 +692,8 @@ You can often force the build to find certain command line tools at certain loca
|
|
645
692
|
`GMAKE`::
|
646
693
|
The location of the GNU-compatible `make` tool.
|
647
694
|
|
695
|
+
NOTE: If you run the installer with `sudo` then environment variables may not be passed properly. Learn more at <<env_vars_and_sudo,Environment variables and sudo>>.
|
696
|
+
|
648
697
|
|
649
698
|
ifdef::apache[]
|
650
699
|
[[working_with_apache_conf]]
|
@@ -823,7 +872,7 @@ To uninstall Phusion Passenger, please first remove all Phusion Passenger
|
|
823
872
|
configuration directives from your web server configuration file(s). After you've
|
824
873
|
done this, you need to remove the Phusion Passenger files.
|
825
874
|
|
826
|
-
- If you installed Phusion Passenger via a Ruby gem, then run `gem uninstall passenger` (or, if you're
|
875
|
+
- If you installed Phusion Passenger via a Ruby gem, then run `gem uninstall passenger` (or, if you're a link:https://www.phusionpassenger.com/enterprise[Phusion Passenger Enterprise] user, `gem uninstall passenger-enterprise-server`).
|
827
876
|
You <<is_ruby_home_or_system_wide_installed,might have to run this as root>>.
|
828
877
|
- If you installed Phusion Passenger via a source tarball, then remove the directory
|
829
878
|
in which you placed the extracted Phusion Passenger files. This directory is the
|
@@ -16,12 +16,12 @@ if it doesn't work on your POSIX-compliant operating system.
|
|
16
16
|
|
17
17
|
=== Where to get support ===
|
18
18
|
|
19
|
-
* link:http://code.google.com/p/phusion-passenger/issues/list[Issue tracker] - report
|
20
|
-
bugs here.
|
21
19
|
* link:http://groups.google.com/group/phusion-passenger[Discussion forum] - post a
|
22
20
|
message here if you're experiencing problems. Support on this forum is provided by the community on a best-effort basis, so a (timely) response is not guaranteed.
|
21
|
+
* link:http://code.google.com/p/phusion-passenger/issues/list[Issue tracker] - report
|
22
|
+
bugs here.
|
23
23
|
* Email support@phusion.nl if you are a link:https://www.phusionpassenger.com/enterprise[Phusion Passenger Enterprise] customer. Please mention your order reference. If you are not an Enterprise customer, we kindly redirect you to the community discussion forum instead.
|
24
24
|
* link:https://www.phusionpassenger.com/commercial_support[Commercial support contracts] are also available.
|
25
|
-
* Report security vulnerabilities to
|
25
|
+
* Report security vulnerabilities to security@phusion.nl. We will do our best to respond to you as quickly as we can, so please do not disclose the vulnerability until then.
|
26
26
|
|
27
27
|
Please consult link:https://www.phusionpassenger.com/support[the Phusion Passenger website] for a full list of support resources.
|
@@ -1,27 +1,53 @@
|
|
1
1
|
[[user_switching]]
|
2
|
-
=== User
|
2
|
+
=== User Switching (security feature) ===
|
3
3
|
|
4
|
+
Phusion Passenger supports automatic 'user switching': by default, it attempts to run applications as the "right" user, instead of running all applications as the same user.
|
5
|
+
|
6
|
+
To better understand the problem, let us consider the situation with PHP.
|
4
7
|
There is a problem that plagues most PHP web hosts, namely the fact that all PHP
|
5
8
|
applications are run in the same user context as the web server. So for
|
6
9
|
example, Joe's PHP application will be able to read Jane's PHP application's
|
7
10
|
passwords. This is obviously undesirable on many servers.
|
8
11
|
|
9
|
-
Phusion Passenger solves this problem
|
10
|
-
|
11
|
-
|
12
|
-
|
13
|
-
|
14
|
-
|
15
|
-
|
16
|
-
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
21
|
-
|
22
|
-
|
23
|
-
|
24
|
-
|
12
|
+
Phusion Passenger's 'user switching' feature solves this problem. Applications are
|
13
|
+
run as the owner of their "startup file". For Ruby apps, the startup file is
|
14
|
+
`config.ru` (Rack and Rails >= 3) or `config/environment.rb` (Rails 1 and 2). For
|
15
|
+
Python apps, the startup file is `passenger_wsgi.py`. So suppose that `config.ru`
|
16
|
+
is owned by user 'joe', then Phusion Passenger will spawn the corresponding
|
17
|
+
application as 'joe' as well. The exact rules are a little bit more complicated,
|
18
|
+
and they're explained further down in this section.
|
19
|
+
|
20
|
+
==== Requirements
|
21
|
+
|
22
|
+
User switching is only enabled when all of the following conditions are met:
|
23
|
+
|
24
|
+
- When not using <<flying_passenger,Flying Passenger>> (this is probably the case):
|
25
|
+
* The
|
26
|
+
ifdef::apache[]
|
27
|
+
<<PassengerUserSwitching,PassengerUserSwitching>>
|
28
|
+
endif::[]
|
29
|
+
ifdef::nginx[]
|
30
|
+
<<PassengerUserSwitching,passenger_user_switching>>
|
31
|
+
endif::[]
|
32
|
+
option must be enabled.
|
33
|
+
* The web server's control process must have root privileges. This is the case on most installations.
|
34
|
+
- When using <<flying_passenger,Flying Passenger>>:
|
35
|
+
* The Flying Passenger daemon must be run with root privileges.
|
36
|
+
|
37
|
+
==== Effects
|
38
|
+
|
39
|
+
When not using Flying Passenger, the following table illustrates the effect for different combinations of the requirements.
|
40
|
+
|
41
|
+
|==========================================================
|
42
|
+
ifdef::apache[]
|
43
|
+
| | **PassengerUserSwitching on** | **PassengerUserSwitching off**
|
44
|
+
endif::[]
|
45
|
+
ifdef::nginx[]
|
46
|
+
| | **passenger_user_switching on** | **passenger_user_switching off**
|
47
|
+
endif::[]
|
48
|
+
| **Web server has root privileges**
|
49
|
+
| User switching enabled.
|
50
|
+
| User switching disabled. Apps are run as
|
25
51
|
ifdef::apache[]
|
26
52
|
<<PassengerDefaultUser,PassengerDefaultUser>> and
|
27
53
|
<<PassengerDefaultGroup,PassengerDefaultGroup>>.
|
@@ -30,21 +56,107 @@ ifdef::nginx[]
|
|
30
56
|
<<PassengerDefaultUser,passenger_default_user>> and
|
31
57
|
<<PassengerDefaultGroup,passenger_default_group>>.
|
32
58
|
endif::[]
|
59
|
+
| **Web server has no root privileges**
|
60
|
+
| User switching disabled. Apps are run as the web server's user.
|
61
|
+
| User switching disabled. Apps are run as the web server's user.
|
62
|
+
|==========================================================
|
63
|
+
|
64
|
+
When using Flying Passenger, the effect is as follows:
|
65
|
+
|
66
|
+
|==========================================================
|
67
|
+
| **Daemon run with root privileges** | User switching enabled.
|
68
|
+
| **Daemon run without root privileges** | User switching disabled. Apps are run as the daemon's user.
|
69
|
+
|==========================================================
|
70
|
+
|
71
|
+
When user switching is enabled, the following rules are followed to determine what user an application should be run as. The first matching rule is the rule that will be followed.
|
72
|
+
|
73
|
+
1. If
|
74
|
+
ifdef::apache[]
|
75
|
+
<<PassengerUser,PassengerUser>> or
|
76
|
+
<<PassengerGroup,PassengerGroup>>
|
77
|
+
endif::[]
|
78
|
+
ifdef::nginx[]
|
79
|
+
<<PassengerUser,passenger_user>> or
|
80
|
+
<<PassengerGroup,passenger_group>>
|
81
|
+
endif::[]
|
82
|
+
are set, then the application will be run as the specified user/group. Thus, these options are a good way to override user switching settings.
|
83
|
+
2. If the startup file is owned by root or an unknown user, then the application will run as the user specified by
|
84
|
+
ifdef::apache[]
|
85
|
+
<<PassengerDefaultUser,PassengerDefaultUser>> and
|
86
|
+
<<PassengerDefaultGroup,PassengerDefaultGroup>>.
|
87
|
+
endif::[]
|
88
|
+
ifdef::nginx[]
|
89
|
+
<<PassengerDefaultUser,passenger_default_user>> and
|
90
|
+
<<PassengerDefaultGroup,passenger_default_group>>.
|
91
|
+
endif::[]
|
92
|
+
3. Otherwise, the application is run as the owner of the startup file.
|
93
|
+
|
94
|
+
==== Caveats & troubleshooting
|
95
|
+
|
96
|
+
If your application regularly encounters permission errors or fails to find certain files, then this is an indication that your application is started as a user that you did not intent it to be run as. Other symptoms include:
|
97
|
+
|
98
|
+
- The application fails to start because Bundler complains that it cannot find gems. This probably indicates that Bundler does not have read access to the directory that contains Bundler-installed gems.
|
99
|
+
- The application fails to start and its error message mentions the path '/nonexistent'. This probably indicates that your application is started as the 'nobody' user. This is because on many systems, the 'nobody' user's home directory is '/nonexistent'.
|
100
|
+
|
101
|
+
To check whether it is indeed the case that your application is started as a different user than you intended to, see <<finding_out_app_user,Finding out what user an application is running as>>.
|
102
|
+
|
103
|
+
The most likely reason why your application is started as 'nobody' is probably because your startup file is owned by 'root', by 'nobody' or by an unknown user. To fix this, change the owner of the startup file to the owner that you want to run the application as.
|
104
|
+
|
105
|
+
Whatever user your application runs as, it must have read access to the <<application_root,application root>>, and read/write access to the application's 'logs' directory.
|
106
|
+
|
107
|
+
[[finding_out_app_user]]
|
108
|
+
==== Finding out what user an application is running as
|
109
|
+
|
110
|
+
To find our what user an application is started as, first access its URL in your browser so that Phusion Passenger starts the application. For example:
|
111
|
+
|
112
|
+
----------------------------------
|
113
|
+
http://www.example.local/
|
114
|
+
----------------------------------
|
115
|
+
|
116
|
+
The application will now either successfully start or fail to start. If it fails to start then you will see an error page that tells you what user the application was being started as. If you do not see the error page in the browser then set
|
117
|
+
ifdef::apache[]
|
118
|
+
<<PassengerFriendlyErrorPages,PassengerFriendlyErrorPages>>
|
119
|
+
endif::[]
|
120
|
+
ifdef::nginx[]
|
121
|
+
<<PassengerFriendlyErrorPages,passenger_friendly_error_pages>>
|
122
|
+
endif::[]
|
123
|
+
on.
|
33
124
|
|
34
|
-
|
35
|
-
|
36
|
-
|
37
|
-
|
125
|
+
If the application successfully started, then run `passenger-status` to find the process's PID:
|
126
|
+
|
127
|
+
------------------------------------------------
|
128
|
+
.---------- General information -----------
|
129
|
+
Max pool size : 6
|
130
|
+
Processes : 1
|
131
|
+
Requests in top-level queue : 0
|
132
|
+
|
133
|
+
.---------- Application groups -----------
|
134
|
+
/webapps/example.local#default:
|
135
|
+
App root: /webapps/example.local
|
136
|
+
Requests in queue: 0
|
137
|
+
* PID: 16915 Sessions: 0 Processed: 1 Uptime: 2s
|
138
|
+
CPU: 0% Memory : 9M Last used: 2s ago
|
139
|
+
------------------------------------------------
|
140
|
+
|
141
|
+
In the above example we see that the PID is 16915. Next, use 'ps' to find out the user that it is running as:
|
142
|
+
|
143
|
+
--------------------------------------------------
|
144
|
+
# ps -o pid,user,comm -p 16915
|
145
|
+
PID USER COMM
|
146
|
+
16915 phusion Passenger RackApp: /webapps/example.local
|
147
|
+
--------------------------------------------------
|
148
|
+
|
149
|
+
As you can see, the application in this example is being run as user 'phusion'.
|
38
150
|
|
39
151
|
|
40
152
|
[[reducing_memory_usage]]
|
41
|
-
===
|
153
|
+
=== Copy-on-write memory support (reducing memory consumption of Ruby applications) ===
|
154
|
+
|
155
|
+
Phusion Passenger automatically leverages operating system virtual memory copy-on-write features in order to reduce the memory usage of Ruby applications. Experience has shown that this reduces memory usage by 33% on average. For this mechanism to work, a Ruby interpreter with a copy-on-write friendly garbage collector is required. The following Ruby interpreters have copy-on-write friendly garbage collectors:
|
42
156
|
|
43
|
-
|
44
|
-
|
45
|
-
Please visit the website for details.
|
157
|
+
- MRI Ruby >= 2.0. Versions prior to 2.0 did not have a copy-on-write friendly garbage collector.
|
158
|
+
- http://www.rubyenterpriseedition.com/[Ruby Enterprise Edition], which was Phusion's branch of MRI Ruby 1.8 with a copy-on-write friendly garbage collector and other enhancement. It has reached End-Of-Life as of 2012, but remains available for legacy systems.
|
46
159
|
|
47
|
-
Note that this feature does not apply to Rack applications.
|
48
160
|
|
49
161
|
[[capistrano]]
|
50
162
|
=== Capistrano recipe ===
|
@@ -86,7 +198,10 @@ end
|
|
86
198
|
=== Bundler support ===
|
87
199
|
|
88
200
|
Phusion Passenger has automatic support for link:http://gembundler.com/git.html[Bundler].
|
89
|
-
|
201
|
+
The support consists of loading your application under the environment defined by your
|
202
|
+
Gemfile. In other words, Phusion Passenger loads your application as if 'bundle exec' was used.
|
203
|
+
|
204
|
+
The Bundler support works as follows:
|
90
205
|
|
91
206
|
- If you have a '.bundle/environment.rb' in your application root, then Phusion
|
92
207
|
Passenger will require that file before loading your application.
|
@@ -104,11 +219,25 @@ have any negative effects.
|
|
104
219
|
Phusion Passenger assumes that you're using Bundler >= 0.9.5. If you don't want Phusion
|
105
220
|
Passenger to run its Bundler support code, e.g. because you need to use an older version
|
106
221
|
of Bundler with an incompatible API or because you use a system other than Bundler, then
|
107
|
-
you can override Phusion Passenger's Bundler support code by creating
|
222
|
+
you can override Phusion Passenger's Bundler support code by creating an empty file
|
108
223
|
'config/setup_load_paths.rb'. If this file exists then it will be required before loading
|
109
224
|
the application startup file. In this file you can do whatever you need to setup Bundler
|
110
225
|
or a similar system.
|
111
226
|
|
227
|
+
[[add_passenger_to_gemfile]]
|
228
|
+
==== Does Phusion Passenger itself need to be added to the Gemfile?
|
229
|
+
|
230
|
+
It is never necessary to add Phusion Passenger to the application's Gemfile. In case of Phusion Passenger Standalone, it is not necessary to execute the `passenger` command through `bundle exec`. The reason for this is because Phusion Passenger automatically loads the Gemfile environment. Most other Ruby application servers do not automatically load the Gemfile environment, which is why they must be added to the Gemfile and be executed with `bundle exec`.
|
231
|
+
|
232
|
+
Even when your application uses any of the Phusion Passenger APIs, you still do not need to add Phusion Passenger to the Gemfile. The only thing you need to do is to put Phusion Passenger API calls inside `if` blocks that check whether Phusion Passenger is active, by checking whether the `PhusionPassenger` namespace is defined:
|
233
|
+
|
234
|
+
[code,ruby]
|
235
|
+
------------------------------------
|
236
|
+
if defined?(PhusionPassenger)
|
237
|
+
...
|
238
|
+
end
|
239
|
+
------------------------------------
|
240
|
+
|
112
241
|
=== Installing multiple Ruby on Rails versions ===
|
113
242
|
|
114
243
|
Each Ruby on Rails applications that are going to be deployed may require a
|
@@ -207,7 +336,7 @@ Applications can use Out-of-Band Work as follows:
|
|
207
336
|
|
208
337
|
Note that even though you can request out-of-band work, there's no guarantee that Phusion Passenger will send an `oob_work` event in a timely manner, if at all. It is also possible that Phusion Passenger sends an `oob_work` event without you ever having requested one. This latter could for example happen if the OOB work is administrator-initiated. Do not make any assumptions in your code.
|
209
338
|
|
210
|
-
Here's an example which implements out-of-band garbage collection using the Out-of-Band framework
|
339
|
+
Here's an example which implements out-of-band garbage collection using the Out-of-Band framework. This example code doesn't do anything when the code is not being run in Phusion Passenger, thanks to the `if` block.
|
211
340
|
|
212
341
|
[source, ruby]
|
213
342
|
-------------------------------------------------
|
@@ -216,24 +345,207 @@ Here's an example which implements out-of-band garbage collection using the Out-
|
|
216
345
|
response.headers["X-Passenger-Request-OOB-Work"] = "true"
|
217
346
|
|
218
347
|
# Somewhere during application initialization:
|
219
|
-
PhusionPassenger
|
220
|
-
|
221
|
-
|
222
|
-
|
223
|
-
|
348
|
+
if defined?(PhusionPassenger)
|
349
|
+
PhusionPassenger.on_event(:oob_work) do
|
350
|
+
# Phusion Passenger has told us that we're ready to perform OOB work.
|
351
|
+
t0 = Time.now
|
352
|
+
GC.start
|
353
|
+
Rails.logger.info "Out-Of-Bound GC finished in #{Time.now - t0} sec"
|
354
|
+
end
|
224
355
|
end
|
225
356
|
-------------------------------------------------
|
226
357
|
|
227
|
-
For your convenience, Phusion Passenger provides a Rack middleware for out-of-band garbage collection. Add
|
358
|
+
For your convenience, Phusion Passenger provides a Rack middleware for out-of-band garbage collection. Add the following to your `config.ru`. Likewise, this example code doesn't do anything when the code is not being run in Phusion Passenger, thanks to the `if` block.
|
228
359
|
|
229
360
|
[source, ruby]
|
230
361
|
----------------------------------------------------
|
231
|
-
|
232
|
-
|
233
|
-
|
234
|
-
|
362
|
+
if defined?(PhusionPassenger)
|
363
|
+
require 'phusion_passenger/rack/out_of_band_gc'
|
364
|
+
|
365
|
+
# Trigger out-of-band GC every 5 requests.
|
366
|
+
use PhusionPassenger::Rack::OutOfBandGc, 5
|
367
|
+
end
|
235
368
|
----------------------------------------------------
|
236
369
|
|
370
|
+
It should be noted that, although the application uses the Phusion Passenger API, it is <<add_passenger_to_gemfile,*not* necessary to add Phusion Passenger to the Gemfile>>.
|
371
|
+
|
237
372
|
References:
|
238
373
|
|
239
|
-
- link:http://blog.phusion.nl/2013/01/22/phusion-passenger-4-technology-preview-out-of-band-work/[The Phusion Blog article which first introduced this feature.]
|
374
|
+
- link:http://blog.phusion.nl/2013/01/22/phusion-passenger-4-technology-preview-out-of-band-work/[The Phusion Blog article which first introduced this feature.]
|
375
|
+
|
376
|
+
[[flying_passenger]]
|
377
|
+
=== Flying Passenger
|
378
|
+
:version: 4.0.6
|
379
|
+
include::enterprise_only.txt[]
|
380
|
+
|
381
|
+
Flying Passenger allows one to decouple Phusion Passenger's life time from the web server's life time, so that the web server can be independently restarted from Phusion Passenger, and from any of the application processes served by Phusion Passenger.
|
382
|
+
|
383
|
+
Normally, Phusion Passenger starts together with the web server, and shuts down together with the web server. The advantages of this default behavior is that it makes Phusion Passenger easy to administer: one only has to deal with the web server process and can expect all relevant processes to be cleaned up after a web server shut down. However this also brings about a disadvantage: every time one restarts the web server (e.g. to make a minor configuration change), Phusion Passenger and all its application processes also get restarted.
|
384
|
+
|
385
|
+
This problem is solved by 'Flying Passenger', which is an advanced mode of operation in Phusion Passenger that allows the web server to be indepedently restarted from Phusion Passenger. When this mode is enabled:
|
386
|
+
|
387
|
+
- One must start Phusion Passenger separately from the web server, namely by starting the Flying Passenger daemon. This daemon must - to an extent - be separately configured and managed from the web server.
|
388
|
+
- The web server must be configured to forward requests to the Flying Passenger daemon.
|
389
|
+
- You should beware of the <<flying_passenger_caveats,caveats and limitations>>.
|
390
|
+
|
391
|
+
==== Requirements
|
392
|
+
|
393
|
+
At this time, this feature is **only available in the Enterprise version of Phusion Passenger for Nginx**. You must have Phusion Passenger for Nginx properly installed.
|
394
|
+
|
395
|
+
==== Basic usage
|
396
|
+
|
397
|
+
Start the Flying Passenger daemon by invoking the `flying-passenger` command. The only required option is `--socket-file`. Depending on whether you wish to enable <<user_switching,User Switching>>, you have to start `flying-passenger` with root privileges or not.
|
398
|
+
|
399
|
+
-------------------
|
400
|
+
$ sudo flying-passenger --socket-file=/var/run/flying-passenger.sock
|
401
|
+
I, [2013-06-14T09:10:13.095339 #77179] INFO -- : Welcome to Flying Passenger 4.1.0
|
402
|
+
I, [2013-06-14T09:10:13.095339 #77179] INFO -- : Starting PassengerWatchdog...
|
403
|
+
I, [2013-06-14T09:10:13.097036 #77179] INFO -- : PassengerWatchdog started on PID 77181
|
404
|
+
...
|
405
|
+
I, [2013-06-14T09:10:13.129017 #77179] INFO -- : PassengerWatchdog initialized properly
|
406
|
+
I, [2013-06-14T09:10:13.129127 #77179] INFO -- : Flying Passenger up and listening on /var/run/flying-passenger.sock!
|
407
|
+
-------------------
|
408
|
+
|
409
|
+
Now configure Phusion Passenger for Nginx to make use of the Flying Passenger daemon, by setting the `passenger_fly_with` option to the socket filename:
|
410
|
+
|
411
|
+
-------------------
|
412
|
+
http {
|
413
|
+
...
|
414
|
+
passenger_fly_with /var/run/flying-passenger.sock;
|
415
|
+
...
|
416
|
+
}
|
417
|
+
-------------------
|
418
|
+
|
419
|
+
After (re)starting Nginx, Nginx + Flying Passenger is fully operational:
|
420
|
+
|
421
|
+
-------------------
|
422
|
+
$ sudo /path-to/nginx
|
423
|
+
-------------------
|
424
|
+
|
425
|
+
You can test it by adding a virtual host for a web app:
|
426
|
+
|
427
|
+
-------------------
|
428
|
+
http {
|
429
|
+
...
|
430
|
+
|
431
|
+
server {
|
432
|
+
listen 80;
|
433
|
+
server_name www.foo.local;
|
434
|
+
root /webapps/foo/public;
|
435
|
+
passenger_enabled on;
|
436
|
+
}
|
437
|
+
}
|
438
|
+
-------------------
|
439
|
+
|
440
|
+
Verify that it works by making an HTTP request to it:
|
441
|
+
|
442
|
+
---------------------------------
|
443
|
+
$ curl http://www.foo.local/
|
444
|
+
---------------------------------
|
445
|
+
|
446
|
+
Now let's verify that restarting the web server does not restart the just-spawned application process. Run `passenger-status` to obtain the PID of the application process:
|
447
|
+
|
448
|
+
---------------------------------
|
449
|
+
$ sudo passenger-status
|
450
|
+
Version: 4.1.0
|
451
|
+
Date : 2013-06-14 09:21:51 -0400
|
452
|
+
.---------- General information -----------
|
453
|
+
Max pool size : 6
|
454
|
+
Processes : 1
|
455
|
+
Requests in top-level queue : 0
|
456
|
+
|
457
|
+
.---------- Application groups -----------
|
458
|
+
/webapps/foo#default:
|
459
|
+
App root: /webapps/foo
|
460
|
+
Requests in queue: 0
|
461
|
+
* PID: 77283 Sessions: 0 Processed: 1 Uptime: 2s
|
462
|
+
CPU: 1% Memory : 8M Last used: 2s ago
|
463
|
+
---------------------------------
|
464
|
+
|
465
|
+
As you can see, the PID of the application process is **77283**. Now let's see what happens if we restart Nginx:
|
466
|
+
|
467
|
+
------------------------
|
468
|
+
$ sudo /path-to/nginx -s stop
|
469
|
+
$ sudo /path-to/nginx
|
470
|
+
$ sudo passenger-status
|
471
|
+
------------------------
|
472
|
+
|
473
|
+
The application process should remain there, unchanged:
|
474
|
+
|
475
|
+
---------------------------------
|
476
|
+
$ sudo passenger-status
|
477
|
+
Version: 4.1.0
|
478
|
+
Date : 2013-06-14 09:21:51 -0400
|
479
|
+
.---------- General information -----------
|
480
|
+
Max pool size : 6
|
481
|
+
Processes : 1
|
482
|
+
Requests in top-level queue : 0
|
483
|
+
|
484
|
+
.---------- Application groups -----------
|
485
|
+
/webapps/foo#default:
|
486
|
+
App root: /webapps/foo
|
487
|
+
Requests in queue: 0
|
488
|
+
* PID: 77283 Sessions: 0 Processed: 1 Uptime: 18s
|
489
|
+
CPU: 1% Memory : 8M Last used: 18s ago
|
490
|
+
---------------------------------
|
491
|
+
|
492
|
+
[[configuring_flying_passenger]]
|
493
|
+
==== Configuring Flying Passenger
|
494
|
+
|
495
|
+
Flying Passenger gets *some* configuration from the web server, but not all. In particular, most web server directives that are only valid in the `http` context, e.g. <<PassengerLogLevel,passenger_log_level>>, have no effect when using Flying Passenger. Instead, you are supposed to pass these configuration directives through command line options to the Flying Passenger daemon. Configuration directives that have no effect on Flying Passenger are documented as such. You can assume that configuration directives that are not documented as such, work fine on Flying Passenger.
|
496
|
+
|
497
|
+
For example, to achieve the same effect as setting passenger_log_level to 2, run the Flying Passenger daemon as follows:
|
498
|
+
|
499
|
+
----------------------------------
|
500
|
+
$ sudo flying-passenger --socket-file=/var/run/flying-passenger.sock --log-level=2
|
501
|
+
----------------------------------
|
502
|
+
|
503
|
+
Currently, not all configuration directives have a Flying Passenger equivalent. Run the following command to see an overview of available options:
|
504
|
+
|
505
|
+
----------------------------
|
506
|
+
$ flying-passenger --help
|
507
|
+
----------------------------
|
508
|
+
|
509
|
+
==== Managing the Flying Passenger daemon
|
510
|
+
|
511
|
+
The Flying Passenger daemon runs in the foreground by default. This is undesirable on server environments. You can make it go into the background by passing `--daemonize`, `--log-file` and `--pid-file`:
|
512
|
+
|
513
|
+
--------------------------------------------------------------------------------
|
514
|
+
$ sudo flying-passenger --socket-file=/var/run/flying-passenger.sock \
|
515
|
+
--daemonize --log-file=/var/log/flying-passenger.log \
|
516
|
+
--pid-file=/var/run/flying-passenger.pid
|
517
|
+
--------------------------------------------------------------------------------
|
518
|
+
|
519
|
+
You can shut down a Flying Passenger daemon by sending SIGINT or SIGTERM to it:
|
520
|
+
|
521
|
+
--------------------------------------------------------------------------------
|
522
|
+
$ kill `cat /var/run/flying-passenger.pid`
|
523
|
+
--------------------------------------------------------------------------------
|
524
|
+
|
525
|
+
We recommend using link:http://cr.yp.to/daemontools.html[daemontools] or link:http://smarden.org/runit/[runit] for managing the Flying Passenger daemon. These tools will allow automatically starting the Flying Passenger daemon at boot, and will automatically restart the daemon if it crashes. You can create and enable a daemontools/runit service as folows:
|
526
|
+
|
527
|
+
--------------------------------
|
528
|
+
$ sudo mkdir /etc/service/flying-passenger
|
529
|
+
$ sudo nano /etc/service/flying-passenger/run
|
530
|
+
#!/bin/sh
|
531
|
+
exec /path-to/flying-passenger \
|
532
|
+
--socket-file=/var/run/flying-passenger.sock \
|
533
|
+
--log-file=/var/log/flying-passenger.log \
|
534
|
+
--pid-file=/var/run/flying-passenger.pid
|
535
|
+
--------------------------------
|
536
|
+
|
537
|
+
Immediately after creating the `run` file, daemontools/runit automatically runs it to start the daemon. Note that the location (`/etc/service`) depends on the OS or Linux distros. Sometimes it's `/service`. Also note that we start the Flying Passenger daemon without `--daemonize`.
|
538
|
+
|
539
|
+
To shut down a daemontools/runit-managed daemon, you need to use `svc -d /etc/service/flying-passenger` (daemontools) or `sv stop /etc/service/flying-passenger` (runit) instead of sending a signal to the process.
|
540
|
+
|
541
|
+
[[flying_passenger_caveats]]
|
542
|
+
==== Caveats and limitations
|
543
|
+
|
544
|
+
Beware of the following caveats and limitations when using Flying Passenger:
|
545
|
+
|
546
|
+
- The Nginx executable **must** be compiled with the same version of Phusion Passenger as the Flying Passenger daemon. Failing to meet this requirement may result in cryptic errors, or may result in certain features not working, until you've fixed the situation. When upgrading Phusion Passenger, you must restart both Nginx and the Flying Passenger daemon.
|
547
|
+
- The <<PassengerRoot,passenger_root>> directive has no effect. When using Flying Passenger, you are not supposed to set `passenger_root`.
|
548
|
+
- When you add a new application to the web server configuration, Flying Passenger will automatically pick up the application's settings and spawn this new application upon the first request to it. However it is not capable of automatically starting the new app before a request has been sent to it (i.e. <<PassengerPreStart,passenger_pre_start>>-like behavior is not available in this case). As a workaround, you can send an HTTP request to your application after starting the daemon, which forces it to spawn application processes.
|
549
|
+
- When you remove an application from the web server configuration, Flying Passenger will not detect the removal and will not shut down the associated application processes. Killing the application processes will also not help, because Flying Passenger will restart them per the (now-removed, but still in the Flying Passenger daemon's memory) <<PassengerMinInstances,passenger_min_instances>> settings. At the moment, there are two ways to get rid of those processes:
|
550
|
+
* Before removing the application from the web server configuration, explicitly set its `passenger_min_instances` to 0. Next, send a request to it, which will cause the Flying Passenger daemon to take over the new `passenger_min_instances 0` option. You can then proceed with removing the application from the web server configuration, and restarting the web server. Finally, kill the PIDs associated to those application processes and remove the application configuration.
|
551
|
+
* Restart the Flying Passenger daemon.
|