1. Support information
1.1. Supported operating systems
Phusion Passenger works on any POSIX-compliant operating system. In other words: practically any operating system on earth, except Microsoft Windows.
Phusion Passenger is confirmed on a large number of operating systems and Linux distributions, including, but not limited to, Ubuntu, Debian, CentOS/Fedora/RHEL, Gentoo, Mac OS X, FreeBSD and Solaris. OpenBSD is supported since version 5.2. Both 32-bit and 64-bit platforms are supported.
Please report a bug or join our discussion forum if it doesn’t work on your POSIX-compliant operating system.
1.2. Where to get support
-
Community discussion forum - post a message here if you’re experiencing problems. Support on this forum is provided by the community on a best-effort basis, so a (timely) response is not guaranteed.
-
Issue tracker - report bugs here.
-
Email support@phusion.nl if you are a 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.
-
Commercial support contracts are also available.
-
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.
Please consult the Phusion Passenger website for a full list of support resources.
2. Installation
2.1. Synopsis
Because Phusion Passenger is designed to run in a wide variety of operating systems and configurations, there are multiple ways to install it. Most users — especially first-time users — will prefer OS-specific installation instructions. These are not only the easiest, but also allow Phusion Passenger to integrate into the operating system in the best way possible. Other users should consult the generic installation instructions.
The steps for upgrading or downgrading Phusion Passenger is almost the same as the steps for installing. All the installation guides in this section will also teach you how to upgrade and downgrade.
2.2. Installing or upgrading on Mac OS X with Homebrew
- Open source
-
Every time we release a new Phusion Passenger version, we make it available through Homebrew. Please note that the Homebrew maintainers have to merge our pull requests manually, so it may take a day or two before a new version shows up in the official Homebrew repository.
-
Update the Homebrew recipes:
brew update
-
Run one of the following, and follow the instructions:
brew install passenger -OR- brew upgrade passenger
-
- Enterprise
-
Phusion Passenger Enterprise is currently not available through Homebrew. Please try one of the other installation methods instead.
2.3. Installing or upgrading on Debian or Ubuntu
We provide and official Phusion Passenger APT repository. This APT repository contains Phusion Passenger packages for multiple versions of Debian and Ubuntu. These packages are automatically built by our build server after we push out a source release, and thus are always up to date with the official source releases.
If you use these packages to install Phusion Passenger then you do not need to run passenger-install-apache2-module or passenger-install-nginx-module. These packages contain all the binaries that you need.
Packages are available for the x86 and x86_64 architectures. Our policy is to support all Ubuntu LTS releases that are still supported by Canonical, plus the latest non-LTS Ubuntu release, plus all Debian releases that are still supported by Debian.
2.3.1. Adding our APT repository
Packages are signed by "Phusion Automated Software Signing (auto-software-signing@phusion.nl)", fingerprint 1637 8A33 A6EF 1676 2922 526E 561F 9B9C AC40 B2F7. Install our PGP key:
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 561F9B9CAC40B2F7
Our APT repository is stored on an HTTPS server so you may need to add HTTPS support for APT:
sudo apt-get install apt-transport-https
Next, create a file /etc/apt/sources.list.d/passenger.list and insert one of the following lines, depending on your distribution.
Phusion Passenger open source:
deb https://oss-binaries.phusionpassenger.com/apt/passenger lucid main deb https://oss-binaries.phusionpassenger.com/apt/passenger precise main deb https://oss-binaries.phusionpassenger.com/apt/passenger saucy main deb https://oss-binaries.phusionpassenger.com/apt/passenger squeeze main deb https://oss-binaries.phusionpassenger.com/apt/passenger wheezy main
Phusion Passenger Enterprise:
deb https://YOUR_ORDER_REFERENCE:YOUR_PASSWORD@www.phusionpassenger.com/enterprise_apt lucid main deb https://YOUR_ORDER_REFERENCE:YOUR_PASSWORD@www.phusionpassenger.com/enterprise_apt precise main deb https://YOUR_ORDER_REFERENCE:YOUR_PASSWORD@www.phusionpassenger.com/enterprise_apt saucy main deb https://YOUR_ORDER_REFERENCE:YOUR_PASSWORD@www.phusionpassenger.com/enterprise_apt squeeze main deb https://YOUR_ORDER_REFERENCE:YOUR_PASSWORD@www.phusionpassenger.com/enterprise_apt wheezy main
Please replace YOUR_ORDER_REFERENCE and YOUR_PASSWORD with your Customer Area login credentials.
After creating /etc/apt/sources.list.d/passenger.list, run:
sudo chown root: /etc/apt/sources.list.d/passenger.list sudo chmod 600 /etc/apt/sources.list.d/passenger.list sudo apt-get update
2.3.2. Installing packages
- Open source
-
sudo apt-get install passenger
- Enterprise
-
-
Download your license key from the Customer Area and save it as /etc/passenger-enterprise-license.
-
Install the packages:
sudo apt-get install passenger-enterprise
-
2.4. Installing or upgrading on Red Hat, Fedora, CentOS or ScientificLinux
YUM repositories with RPMs are maintained by Erik Ogan and Stealthy Monkeys Consulting. Only packages for the open source version of Phusion Passenger are provided. Phusion Passenger Enterprise customers should use the generic RubyGems installation method or the generic tarball installation method instead.
If you use YUM to install Phusion Passenger then you do not need to run passenger-install-apache2-module or passenger-install-nginx-module. The YUM packages contain all the binaries that you need. You also don’t need to modify any Apache or Nginx configuration to get them to load Phusion Passenger, the packages provide configuration snippets for you as well.
Step 1: Import the Stealthy Monkeys Consulting’s GPG key
rpm --import http://passenger.stealthymonkeys.com/RPM-GPG-KEY-stealthymonkeys.asc
Step 2: Install the release package
Install the passenger-release package from the main repository.
Fedora Core 17:
yum install http://passenger.stealthymonkeys.com/fedora/17/passenger-release.noarch.rpm
Fedora Core 16:
yum install http://passenger.stealthymonkeys.com/fedora/16/passenger-release.noarch.rpm
Fedora Core 15:
yum install http://passenger.stealthymonkeys.com/fedora/15/passenger-release.noarch.rpm
Fedora Core 14:
yum install http://passenger.stealthymonkeys.com/fedora/14/passenger-release.noarch.rpm
RHEL 6 / CentOS 6 / ScientificLinux 6: (Note: these packages depend on EPEL.)
yum install http://passenger.stealthymonkeys.com/rhel/6/passenger-release.noarch.rpm
RHEL 5 / CentOS 5 / ScientificLinux 5: (Note: these packages depend on EPEL.)
rpm -Uvh http://passenger.stealthymonkeys.com/rhel/5/passenger-release.noarch.rpm
Step 3: Install the right Phusion Passenger package
From there you can use YUM to install packages. For example, try one of these:
Phusion Passenger for Apache:
yum install mod_passenger
Phusion Passenger for Nginx:
yum install nginx-passenger
Phusion Passenger Standalone:
yum install passenger-standalone
Building your own packages
There are instructions for building your own packages and Yum repositories in the rpm directory ReadMe within the GitHub repository.
2.5. Generic installation, upgrade and downgrade method: via RubyGems
RubyGems is only used as a method to obtain the Phusion Passenger files, so in case you have multiple Ruby versions it does not matter which Ruby’s RubyGems you use for installation. Once installed, Phusion Passenger can work with all other Ruby versions on your system. This is explained in Phusion Passenger and its relationship with Ruby.
Step 1: figuring out whether your Ruby is installed in the home directory or system-wide
Ruby may either be installed in the home directory, or system-wide. If it’s installed system-wide then we will want to install gems system-wide as well, so you need to switch to a root prompt first. If Ruby is installed in the home directory then we will want to install gems to the home directory as well, as a normal user.
To find out which case applies, run the following command to find out where the ruby command is:
which ruby
Do you see a filename that references /home or /Users? If so then your Ruby interpreter is installed in your home directory and you can proceed to step 2. Otherwise, you need to switch to a root prompt by running one of the following commands:
-
Are you using RVM? Run rvmsudo -s
-
Are you not using RVM, or do you not know what RVM is? Run sudo -s
-
Is sudo not installed on your system? Run su -c bash
You must maintain this root prompt throughout this installation guide.
Step 2: install the gem
- Open Source
-
Install the latest gem to obtain the files for the latest stable version of the open source Phusion Passenger:
gem install passenger
- Enterprise
-
First, download the license key from the Customer Area and save it as /etc/passenger-enterprise-license.
Next, add the Phusion Passenger Enterprise gem server to your RubyGems source list:
gem source --add https://YOUR_ORDER_REFERENCE:YOUR_PASSWORD@www.phusionpassenger.com/enterprise_gems/
Substitute YOUR_ORDER_REFERENCE and YOUR_PASSWORD with your Customer Area login credentials. And notice the trailing slash in the URL! It is very important.
Finally, install the latest gem to obtain the files for the latest stable version of the open source Phusion Passenger:
gem install passenger-enterprise-server
2.6. Generic installation, upgrade and downgrade method: via tarball
Step 1: installing Ruby
Phusion Passenger supports multiple languages and its core is written in C++, but its installer and administration tools are written in Ruby, so you must install Ruby.
Even though Ruby is required, Ruby will normally not be loaded during normal operation unless you deploy a Ruby web application on Phusion Passenger. Phusion Passenger’s dependency on Ruby is very minimal. See Phusion Passenger and its relationship with Ruby for details.
Debian, Ubuntu |
sudo apt-get update |
Red Hat, CentOS, ScientificLinux, Amazon Linux |
Enable EPEL, then run as root: |
Mac OS X |
No action needed. Ruby is installed by default. |
Other operating systems |
Install Ruby from the Ruby website. |
Step 2: download and extract the tarball
- Open Source
-
Download the open source Phusion Passenger tarball from the Phusion Passenger website.
Older versions can be found in the release archive.
- Enterprise
-
Phusion Passenger Enterprise customers can download the Phusion Passenger Enterprise tarball from the Customer Area.
Also be sure to download the license key and save it as /etc/passenger-enterprise-license.
Once you have downloaded the tarball, pick a location to extract it to. You can pick any location. A good location is /opt/passenger. Create this directory and extract the tarball as follows:
mkdir /opt/passenger cd /opt/passenger tar xzvf /location-to/passenger-x.x.x.tar.gz cd /opt/passenger/passenger-x.x.x
Note that passenger-x.x.x should be passenger-enterprise-server-x.x.x if you’re using Phusion Passenger Enterprise.
Step 3: adding the Phusion Passenger tools to PATH
Edit /etc/bashrc (or /etc/bash.bashrc on some systems) and append the following to the end of the file:
export PATH=/opt/passenger/passenger-x.x.x/bin:$PATH
Finally, restart all your shell sessions in order to activate this change. The installation is now complete.
2.7. Upgrading from open source to Enterprise
Phusion Passenger comes in two variants: an open source version, as well as an Enterprise version which introduces a myriad of useful features that can improve stability and performance and efficiency.
Customers who have bought Phusion Passenger Enterprise can upgrade their open source installation to Enterprise as follows:
-
Install the Enterprise version by following one of the installation guides in this section (e.g. RubyGems generic installation or tarball generic installation).
The uninstallation is necessary because the Enterprise Ruby gem has a different gem name (passenger-enterprise-server instead of passenger), but the same administration command names (e.g. passenger-status). Uninstalling the open source version avoids any conflicts.
2.8. Cryptographic verification of installation files
2.8.1. Synopsis
We digitally sign various files with our GPG key so that you can check whether they’re legit, i.e. whether they really came from Phusion and haven’t been tampered with by a third party. We apply signing since the open source version 4.0.0 RC 4, or the Enterprise version 4.0.0 RC 1.
2.8.2. Importing the Phusion Software Signing key
Phusion’s GPG key for signing software is as follows:
Phusion Software Signing (software-signing@phusion.nl) Short key ID: 0x0A212A8C Long key ID: 0x2AC745A50A212A8C Fingerprint: D5F0 8514 2693 9232 F437 AB72 2AC7 45A5 0A21 2A8C
This key is stored at the Phusion website and at the key servers sks-keyservers.net and keyserver.ubuntu.com. You can import it to your keyring with one of these command:
gpg --keyserver pool.sks-keyservers.net --search-keys 0x2AC745A50A212A8C # -OR- gpg --keyserver keyserver.ubuntu.com --search-keys 0x2AC745A50A212A8C
The Phusion Software Signing key is only used for signing software. It’s never used for signing emails or for encrypting files, so please be suspicious if you encounter usage of this key outside the context of signing software, and alert us at support@phusion.nl. Include "notspam" in the message to bypass our spam filter.
The email address software-signing@phusion.nl redirects to info@phusion.nl so it’s safe to send email there.
2.8.3. Verifying the Phusion Software Signing key
The Phusion Software Signing key is also signed by the Phusion founders. Their keys are as follows:
Hongli Lai (hongli@phusion.nl) Short key ID: 4B6F4332 Long key ID: 06A131094B6F4332 Fingerprint: 64E8 0420 FC6A 499F 9E1F 81FA 06A1 3109 4B6F 4332
Ninh Bui (ninh@phusion.nl) Short key ID: 6FAF3782 Long key ID: BA8DA3F46FAF3782 Fingerprint: 353A 398C 49AF 5CD5 74A0 656C BA8D A3F4 6FAF 3782
Both keys are stored at both sks-servers.net and keyserver.ubuntu.com. Import them with:
gpg --keyserver pool.sks-servers.net --search-keys 0x06A131094B6F4332 gpg --keyserver pool.sks-servers.net --search-keys 0xBA8DA3F46FAF3782 # -OR- gpg --keyserver keyserver.ubuntu.com --search-keys 0x06A131094B6F4332 gpg --keyserver keyserver.ubuntu.com --search-keys 0xBA8DA3F46FAF3782
2.8.4. Verifying the gem and tarball
You can find the open source version’s gem and tarball GPG signatures at https://www.phusionpassenger.com/file_releases. The Enterprise version’s GPG signatures can be found in the Customer Area. All signatures have the .asc extension. Once you have imported our key, you can verify the validity of a file against its signature as follows:
$ gpg --verify passenger-x.x.x.tar.gz.asc passenger-x.x.x.tar.gz gpg: Signature made Mon Mar 11 09:45:46 2013 CET using RSA key ID 0A212A8C gpg: Good signature from "Phusion Software Signing <software-signing@phusion.nl>"
2.8.5. Verifying Git signatures
Tags in the Git repository for the open source version are also tagged. You can verify a Git tag as follows:
$ git tag --verify release-x.x.x object d886f34b5705e4314feccaf0d77b9a38416e15e0 type commit tag release-4.0.0.rc5 tagger Hongli Lai (Phusion) <hongli@phusion.nl> 1362993117 +0100 This is a tag message. gpg: Signature made Mon Mar 11 10:12:02 2013 CET using RSA key ID 0A212A8C gpg: Good signature from "Phusion Software Signing <software-signing@phusion.nl>"
2.8.6. Verifying DEB and RPM packages
The DEB and RPM packages are signed with the signatures of the respective packagers. They are automatically checked upon installation.
2.8.7. Revocation
In the event our key is compromised, we will revoke the key and upload the revocation information to sks-servers.net and keyserver.ubuntu.com. However your system will not know about the revocation until you update the keys from the keyservers. You should update your keys regularly (e.g. once a week) by invoking:
gpg --refresh-keys --keyserver pool.sks-servers.net # -OR- gpg --refresh-keys --keyserver keyserver.ubuntu.com
If you installed Phusion Passenger through our APT repository, then you should update APT’s keyring from time to time as well:
sudo apt-key adv --refresh-keys --keyserver keyserver.ubuntu.com
2.9. Customizing the compilation process
The Phusion Passenger compilation process can be customized with environment variables. You can learn more about environment variables in About environment variables.
2.9.1. Setting the compiler
You can force the Phusion Passenger build system to use a specific C or C++ compiler by setting the CC and CXX environment variables. These may be set to any arbitrary shell commands.
For example, contributors who want to hack on Phusion Passenger may want to use Clang for faster compilation and ccache for faster recompilation, and may want to enable more error-catching compilation flags:
export CC='ccache clang -fcolor-diagnostics -Qunused-arguments -fcatch-undefined-behavior -ftrapv' export CXX='ccache clang++ -fcolor-diagnostics -Qunused-arguments -fcatch-undefined-behavior -ftrapv'
|
If you run the installer with sudo then environment variables may not be passed properly. Learn more at Environment variables and sudo. |
2.9.2. Adding additional compiler or linker flags
On some systems, C/C++ libraries and headers that Phusion Passenger requires may be located in a non-standard directory. You can force the Phusion Passenger build system to look in those locations by injecting compiler and linker flags using the following environment variables:
- EXTRA_PRE_CFLAGS
-
These flags are injected into all C compiler invocations that involve compiling C or C++ source files. This includes compiler invocations that compile and link. The flags are injected at the beginning of the command string, even before EXTRA_PRE_LDFLAGS.
- EXTRA_CFLAGS
-
Similar to EXTRA_PRE_CFLAGS, but injected at the end of the command string, before EXTRA_LDFLAGS.
- EXTRA_PRE_CXXFLAGS
-
Similar to EXTRA_PRE_CFLAGS, but for C++ compiler invocations.
- EXTRA_CXXFLAGS
-
Similar to EXTRA_CFLAGS, but for C++ compiler invocations.
- EXTRA_PRE_LDFLAGS
-
These flags are injected into all C/C++ compiler invocations that involve linking. This includes compiler invocations that compile and link. The flags are injected at the beginning of the command string, but after EXTRA_PRE_CFLAGS and EXTRA_PRE_CXXFLAGS.
- EXTRA_LDFLAGS
-
Similar to EXTRA_PRE_LDFLAGS, but injected at the very end of the command string, even after EXTRA_CFLAGS and EXTRA_CXXFLAGS.
- EXTRA_C_LDFLAGS
-
Similar to EXTRA_LDFLAGS, but only injected for C executable linking commands. Injected right after EXTRA_LDFLAGS.
- EXTRA_CXX_LDFLAGS
-
Similar to EXTRA_LDFLAGS, but only injected for C++ executable linking commands. Injected right after EXTRA_LDFLAGS.
- PASSENGER_THREAD_LOCAL_STORAGE
-
Setting this to 1 will enable the PASSENGER_THREAD_LOCAL_STORAGE macro, which forcefully disables the use of thread-local storage inside the Phusion Passenger codebase. Setting this environment variable is useful on systems that have broken support for thread-local storage, despite passing our build system’s check for proper thread-local storage support. At the time of writing, one user has reported that Ubuntu 12.04 32-bit has broken thread-local storage report although neither the reporter nor us were able to reproduce the problem on any other systems running Ubuntu 12.04 32-bit. Note that this flag has no effect on non-Phusion Passenger code.
|
|
If you run the installer with sudo then environment variables may not be passed properly. Learn more at Environment variables and sudo. |
2.9.3. Forcing location of command line tools and dependencies
The Phusion Passenger build system attempts to autodetect many things by locating relevant helper tools. For example, to find out which compiler flags it should use for compiling Apache modules, it locates the apxs2 command and queries it. To find out which compiler flags it should use for libcurl, it queries the curl-config command. These commands may not be in $PATH, or even when they are you may want to use a different one.
You can force the build to find certain command line tools at certain locations by using the following environment variables:
- HTTPD
-
The location of the httpd executable (the Apache server executable).
- APXS2
-
The location of the apxs2 executable (the Apache module developer tool). Only used by passenger-install-apache2-module.
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.
For example, if your Apache installation is located in /opt/lamp/apache2, then you can run the installer as follows:
$ sudo bash # export HTTPD=/opt/lampp/apache2/bin/apache # export APXS2=/opt/lampp/apache2/bin/apxs # passenger-install-apache2-module
- APR_CONFIG
-
The location of the apr-config executable (the Apache Portable Runtime developer tool).
- APU_CONFIG
-
The location of the apu-config executable (the Apache Portable Runtime Utility developer tool).
- MAKE
-
The location of a make tool. It does not matter which implementation of make this is.
- GMAKE
-
The location of the GNU-compatible make tool.
|
If you do not know what environment variables are, or how to use them, then please read Environment variables and sudo. NOTE: If you run the installer with sudo then environment variables may not be passed properly. Learn more at Environment variables and sudo. |
2.10. Uninstalling
-
If you installed Phusion Passenger via a Ruby gem, then run gem uninstall passenger (or, if you’re a Phusion Passenger Enterprise user, gem uninstall passenger-enterprise-server). You might have to run this as root.
-
If you installed Phusion Passenger via a source tarball, then remove the directory in which you placed the extracted Phusion Passenger files. This directory is the same as the one pointed to the by PassengerRoot/passenger_root configuration directive.
-
If you installed Phusion Passenger through APT or YUM, then use them to uninstall Phusion Passenger.
-
If you installed Phusion Passenger through Homebrew, then run brew uninstall passenger.
2.11. Moving to a different directory
If you installed Phusion Passenger through a tarball then you can move the Phusion Passenger directory to another location. This is not possible if you used any of the other installation methods.
First, move the directory to whereever you like:
mv /opt/passenger/passenger-4.0.0 /usr/local/passenger-4.0.0
If you used the tarball installation method and you added Phusion Passenger’s bin subdirectory to PATH, then you must update your PATH with the new location. Open /etc/bashrc (or /etc/bash.bashrc on some systems) and change:
export PATH=/opt/passenger/passenger-4.0.0/bin:$PATH
to:
export PATH=/usr/local/passenger-4.0.0/bin:$PATH
Finally, restart all your shell sessions to activate the PATH change.
3. Usage
Go to your application’s root directory, and run:
passenger start
This will start Phusion Passenger on port 3000. If you want to run it on a different port, use the -p option, e.g.:
passenger start -p 8000
See --help for all available options.
4. Troubleshooting
4.1. Generic troubleshooting tips
One of the first things you should do upon encountering a problem, is to check Phusion Passenger Standalone log file. This is typically located in log/passenger.[PORT NUMBER].log. Most problems are logged to this file.
If neither the logs nor this troubleshooting guide can help you, then please check out our support resources.
4.2. Upon uploading a file, Phusion Passenger reports "client_body_temp/00000000xx failed (2: No such file or directory)"
- Symptoms
-
When performing an HTTP POST call, the request sometimes fails, with Phusion Passenger reporting an error along the lines of:
/tmp/passenger-standalone.8583/client_body_temp/0000000022" failed (2: No such file or directory), client: 127.0.0.1, server: www.foo.com
- Cause
-
Phusion Passenger buffers HTTP POST bodies (file uploads) to a temporary directory, by default /tmp/passenger-standalone.xxx. This error means that Phusion Passenger that that directory has been removed, probably by some other program.
- Solution
-
Tell Phusion Passenger to use a different directory to store its temporary files passing the --temp-dir command line option. For example:
mkdir $HOME/tmp cd /path-to-your-app passenger start --temp-dir=$HOME/tmp
5. Appendix: About environment variables
The Phusion Passenger compilation process can be customized with environment variables.
Environment variables are named values that affect how the system works. For example they tell the system where to look for commands (the PATH variable) or where to look for libraries (LD_LIBRARY_PATH). Their names are often in all-uppercase. Sometimes people refer to an environment variable with a dollar sign $ in front, but that’s the same thing: when people say "the $PATH environment variable" they mean "the PATH environment variable". This is because the dollar sign $ is a shell syntax for refering to an environment variable, as you will learn later.
Environment variables are set on a per-process basis, but they are inherited by child processes. This means that if you set environment variables in process A, another already running process B will not see these new environment variables. But if A spawns a child process C, then C will have all environment variables that A had. If you once again change the environment variables in A, then C will not see the changes.
The per-process nature of environment variables some implications. When you set environment variables in your bashrc or other bash startup files…
-
…only newly spawned bash shells see them.
-
…the web server usually does not see them, because the web server tends to be started from init scripts, not from bash.
-
…cron jobs do not see them, because cron jobs' environment variables are entirely dictated by their crontabs.
|
|
Because this chapter is meant for beginners, it assumes that the reader uses the bash shell. This chapter does not describe instructions for zsh, csh or other shells. We assume that users of other shells are familiar with the Bourne shell syntax, and know how to apply the instructions in this chapter in their shells' native syntaxes. |
5.1. Working with environment variables
You can see all environment variables in your shell by running the following command:
env
You can set an evironment variable with the syntax export <NAME>=<VALUE>. For example, to set the APXS2 variable to the value /usr/sbin/apxs2:
export APXS2=/usr/sbin/apxs2
Any process that you run from your shell from that point on will have said environment variable:
export APXS2=/usr/sbin/apxs2 ruby -e 'p ENV["APXS2"]' # => "/usr/sbin/apxs2"
|
|
The "export" keyword is important
You must set the export keyword. If you omit the export keyword then the environment variable will not be visible to other processes: APXS2=/usr/sbin/apxs2 ruby -e 'p ENV["APXS2"]' # => nil |
You can reference an environment variable in your shell by typing the $ sign followed by the environment variable’s name. For example, to see the value of the PATH variable:
echo $PATH
You can also use this trick to extend the value of an environment variable:
export PATH=/usr/bin # Prepends '/opt/local/bin', so that it becomes /opt/local/bin:/usr/bin export PATH=/opt/local/bin:$PATH # Appends '/usr/local/bin', so that it becomes /opt/local/bin:/usr/bin:/usr/local/bin export PATH=$PATH:/usr/local/bin
5.2. The PATH environment variable
The PATH environment variable dictates where the system looks for command. It is a colon-separated list of directories. If you get a "command not found" error while you know that the command is installed, then setting PATH will help. For example suppose that the command frobnicator is in /opt/local/bin:
user@localhost bash$ frobnicator bash: frobnicator: command not found
We verify that /opt/local/bin is not in PATH:
user@localhost bash$ echo $PATH /bin:/usr/bin:/usr/local/bin
We can run frobnicator through it’s full path…
user@localhost bash$ /opt/local/bin/frobnicator
# => success!
…or we can add /opt/local/bin to PATH.
user@localhost bash$ export PATH=$PATH:/opt/local/bin user@localhost bash$ frobnicator # => success!
5.2.1. Adding Phusion Passenger’s administration tools to PATH
If you get a "command not found" error when invoking one of the Phusion Passenger administration tools (e.g. passenger-status or passenger-memory-stats then that means the tools are not in PATH, so you need to add them.
-
If you installed Phusion Passenger with RubyGems, then the tools are in your RubyGems executable path. You can view the gem path using the command gem env:
$ gem env RubyGems Environment: - RUBYGEMS VERSION: 1.8.15 - RUBY VERSION: 1.8.7 (2011-12-28 patchlevel 357) [i686-darwin10.8.0] - INSTALLATION DIRECTORY: /opt/ruby-enterprise-1.8.7-2010.01/lib/ruby/gems/1.8 - RUBY EXECUTABLE: /opt/ruby-enterprise-1.8.7-2010.01/bin/ruby - EXECUTABLE DIRECTORY: /opt/ruby-enterprise-1.8.7-2010.01/bin <--------- !! - RUBYGEMS PLATFORMS: - ruby - x86-darwin-10 - GEM PATHS: - /opt/ruby-enterprise-1.8.7-2010.01/lib/ruby/gems/1.8 - /Users/hongli/.gem/ruby/1.8 - GEM CONFIGURATION: - :update_sources => true - :verbose => true - :benchmark => false - :backtrace => false - :bulk_threshold => 1000 - "gem" => "--no-ri --no-rdoc" - REMOTE SOURCES: - http://rubygems.org/As you can see, the RubyGems executable path in the example happens to be /opt/ruby-enterprise-1.8.7-2010.01/bin. So that directory must be added to PATH.
-
If you installed Phusion Passenger using the tarball, then the tools are in the bin subdirectory of the Phusion Passenger tarball directory that you extracted. For example, if you extracted passenger-4.9.0.tar.gz inside /opt, then the tools are located in /opt/passenger-4.0.9/bin. In that case, you need to add /opt/passenger-4.0.9/bin to your PATH.
-
If you installed Phusion Passenger using native OS packages, then some Phusion Passenger administration tools are in /usr/bin, while others are in /usr/sbin. If you are not logged in as root, then /usr/sbin may not be in PATH, which would explain why you get a "command not found" when trying to invoke some of the tools. You should /usr/sbin to PATH.
-
If you are unsure where your Phusion Passenger directory is then you can use the find command to look them up. Go to the root directory and invoke find with sudo:
$ cd / $ sudo find . -name passenger-status /usr/local/passenger/bin/passenger-status
In this example, the administration tools happen to be in /usr/local/passenger/bin, so you must add that to PATH.
|
|
You may still get a "command not found" when invoking the tools through sudo, even after you’ve added the relevant directory to PATH. Please read Environment variables and sudo to learn more. |
5.3. Making environment variables permanent
When you exit your shell, the evironment variable changes are lost. There is no standard method to set environment variables system-wide, so you have to set them in different configuration files for different services.
5.3.1. bash
To make environment variables permanent for future bash sessions for the current user, add them to your ~/.bashrc:
echo 'export FOO=bar' >> ~/.bashrc echo 'export PATH=/usr/local/bin:$PATH' >> ~/.bashrc
To make them permanent for future bash sessions for all users, add them to /etc/bashrc.
|
|
Depending on the system, the bashrc file may have a different filename. On Debian and Ubuntu, it’s /etc/bash.bashrc. |
5.3.2. Apache
|
|
This subsection describes how to set environment variables on Apache itself, not on apps served through Phusion Passenger for Apache. The environment variables you set here will be passed to all apps, but you cannot customize them on a per-app basis. See also Setting environment variables on Phusion Passenger-served apps. |
On Debian and Ubuntu, with an Apache installed through apt, Apache environment variables are defined in the file /etc/apache2/envvars. This is a shell script so environment variables must be specified with the shell syntax.
On Red Hat, Fedora, CentOS and ScientificLinux, with an Apache installed through YUM, Apache environment variables are defined in /etc/sysconfig/httpd.
On OS X they are defined in /System/Library/LaunchDaemons/org.apache.httpd.plist, as explained here on Stack Overflow.
On other systems, or if you did not install Apache through the system’s package manager, the configuration file for environment variables is specific to the vendor that supplied Apache. There may not even be such a configuration file. You should contact the vendor for support.
5.3.3. Nginx
|
|
This subsection describes how to set environment variables on Nginx itself, not on apps served through Phusion Passenger for Nginx. The environment variables you set here will be passed to all apps, but you cannot customize them on a per-app basis. See also Setting environment variables on Phusion Passenger-served apps. |
If you installed Nginx through the Brightbox packages, then you can define environment variables in /etc/default/nginx. This is a shell script so you must use the export FOO=bar syntax.
Otherwise, environment variables are best set through the script which starts Nginx. For example, if you installed Nginx from source and you used then you should edit that script to define the environment variables. Those init scripts are regular shell scripts, so use the export FOO=bar syntax. Just make sure your set your environment variables before the script starts Nginx.
|
|
Setting environment variables on Nginx has no effect on the Flying Passenger daemon because the daemon is started seperately. You should set the environment variables in the shell right before starting the daemon. |
5.3.4. cron
To make environment variables permanent for cron jobs, add those variables to the relevant crontab. But note that inside crontabs you cannot refer to existing environment variables with the $ syntax because crontabs are not shell scripts. You have to specify the entire value.
# Environment variable definitions FOO=bar APXS2=/usr/sbin/apxs2 # **WRONG!** You cannot refer to existing variables with the `$` syntax! PATH=/usr/bin:$PATH # **WRONG!** You cannot use the 'export' keyword! export PATH=/usr/bin:/usr/local/bin # Correct: PATH=/usr/bin:/usr/local/bin # Jobs: # m h dom mon dow command * * * * * frobnicator
5.3.5. Phusion Passenger-served apps
You can pass environment variables to Phusion Passenger-served apps through various methods:
-
When running Apache, use the PassEnv and SetEnv directives of mod_env. This is supported starting from Phusion Passenger 4.0.
-
When running Nginx, use the env directive. Unlike Apache, Nginx’s env directive can only be set globally and cannot be customized on a per-virtual host basis.
-
Through your bashrc. Starting from version 4.0, Phusion Passenger 4.0 spawns applications through bash and inherit all bash environment variables. Phusion Passenger Standalone tends to be started from the shell and thus inherits all environment variables set by the shell.
-
Through Apache and Nginx, as described earlier in this chapter. Any environment variables that you set on Apache and Nginx itself are inherited by Phusion Passenger, and thus by Phusion Passenger-served apps as well.
-
Through the application itself. Most programming languages provide APIs for setting environment variables. For example in Ruby you can write:
ENV['FOO'] = 'bar'
In Python you can write:
import os os.environ['FOO'] = 'bar'
5.4. Environment variables and sudo
The sudo command resets all environment variables before running the specified command, for security reasons. So if you set environment variables before running sudo passenger-install-xxx-module, sudo passenger-status or any other commands, then the environment variables are not correctly passed to the command. You can solve this by running sudo with -E (preserve environment variables):
user@localhost bash$ export APXS2=/usr/sbin/apxs2 user@localhost bash$ sudo -E passenger-install-apache2-module
Alternatively, you can obtain a root prompt with sudo first, and then set the environment variables, before running any further commands:
user@localhost bash$ sudo -s Password: ... root@localhost bash# export APXS2=/usr/sbin/apxs2 root@localhost bash# passenger-install-apache2-module