passenger 1.0.1

data/doc/Security of user switching support.txt

@@ -0,0 +1,197 @@
+Security of user switching support in Passenger
+===============================================
+
+Problem description
+-------------------
+TIP: It is strongly recommended that you first read our
+link:Architectural%20overview.html[Architectural Overview].
+
+A straightforward implementation of Passenger will spawn Rails applications in
+the same user context as Apache itself. On server machines which host multiple
+websites for multiple users, this may not be desired. All Rails applications
+spawned by Passenger will be able to read and write to all directories that the
+web server can. So for example, Joe's Rails applications could read Jane's
+Rails application's 'database.yml' or delete her application files. This is
+also a problem that typically plagues PHP web hosts.
+
+There are multiple ways to solve this problem. The goal of this document is to
+inform the reader about the solutions have we have analyzed, so that
+Passenger's security may be peer reviewed.
+
+
+Analysis of possible solutions
+------------------------------
+It seems that the only way to solve this problem on Unix, is to run each Rails
+application server as its owner's user and group. Passenger can make use of
+one of the following methods to implement this:
+
+ 1. Apache (and thus Passenger) must already be running as root.
+ 2. Using Apache's suEXEC.
+ 3. A setuid root wrapper application must exist, to allow non-root processes
+    to obtain root privileges (or at least, the privilege to switch user).
+ 4. For each user $X that Passenger will need to switch to, there must exist
+    a setuid $X wrapper application.
+ 5. Using 'su'.
+ 6. Using 'sudo'.
+
+Let us take a look at each method in detail.
+
+[[apache_root]]
+Apache must already be running as root
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+First, let us take a look at the typical Apache setup, in which Apache is bound
+to port 80, and uses the prefork MPM. Binding to any port lower than 1024
+requires root privileges, so Apache is typically run as root. This poses an
+unacceptable security risk, so Apache's prefork MPM will, upon receiving an
+HTTP request, spawn a child process with the privileges of a normal user,
+typically 'www-data' or 'nobody'.
+See http://httpd.apache.org/docs/2.2/mod/prefork.html[the documentation for the
+prefork MPM] - in particular the ``User'' and ``Group'' directives - for details.
+The process which is responsible for spawning child processes (also called the
+control process) is run as root. This is also true for
+http://httpd.apache.org/docs/2.2/mod/worker.html[the worker MPM].
+
+Since Passenger has access to the control process, in the typical Apache setup,
+Passenger can already launch Rails applications as a different user. But now we
+have to ask this question:
+
+=================================
+If Apache is not running as root, are there still any Passenger users who
+want to run Rails applications as different users?
+=================================
+
+If the answer is yes, then we cannot use this method.
+
+The advantage of this method is that setting up Apache to run as root is
+incredibly easy, and requires no new framework to be written. However, testing
+this method in automated unit tests will require running the unit test suit as
+root.
+
+Using Apache's suEXEC
+~~~~~~~~~~~~~~~~~~~~~
+Apache's http://httpd.apache.org/docs/2.0/suexec.html[suEXEC] allows one to
+run CGI processes as different users. But it seems that suEXEC can only be
+used for CGI, and is not a general-purpose mechanism. The
+http://alain.knaff.lu/howto/PhpSuexec/[PHP-suEXEC] software allows one to run
+PHP applications via suEXEC, but it requires patching suEXEC. If Passenger is
+to use suEXEC, then it is likely that we'll have to patch suEXEC. The suEXEC
+website strongly discourages patching.
+
+Using a setuid root wrapper application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If we use this method, we must be extremely careful. It must not be possible
+for arbitrary processes to gain root privileges. We want Passenger, and only
+Passenger, to be able to gain root privileges.
+
+There are multiple ways to implement this security. The first one is to use
+a password file, which only Apache and the wrapper can read, through
+the use of proper file permissions. The password file must never be world
+readable or writable.
+
+It works as follows:
+
+1. Passenger runs the wrapper.
+2. Passenger passes the content of the password file to the wrapper, via
+   an anonymous pipe (or some other anonymous channel, that no other
+   processes can access).
+3. The wrapper checks whether the passed content is the same as what is in
+   the password file. If it is, then it is proven that whatever application
+   ran the wrapper has read access to the password file, and thus is authorized
+   to use the wrapper.
+
+An obvious problem that arises is: how does the wrapper locate its own password
+file? We obviously do not want to be able to specify the password filename as
+an argument to the wrapper: that would defeat the point of the password file.
+The solution is that the filename is to be hardcoded into the binary during
+compile time.
+
+Another way to implement security is to use a whitelist of users that are
+allowed to use the wrapper. The wrapper can then check whether the calling
+process's user is in the whitelist.
+
+Writing a wrapper is not too hard. Furthermore, unit tests do not have to be
+run as root, in contrast to the run-Apache-as-root method.
+
+[[setuid_root]]
+Using a setuid $X wrapper application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A setuid $X wrapper will work in a fashion similar to the setuid root wrapper,
+i.e. it will use a password file for authorization.
+
+Passenger does not spawn Rails applications itself, but does so via the spawn
+server. This spawn server is also responsible for preloading the Rails
+framework and the Rails application code, in order to speed up the spawning
+of Rails applications. See the design document of the spawn server for details.
+The spawn server never calls `exec()`: doing so will make preloading useless.
+If Passenger is to use a setuid $X wrapper, then it must start the spawn
+server via the wrapper. The spawn server itself cannot use the wrapper.
+
+However, doing so will make preloading less efficient. Passenger will be forced
+to run a spawn server for each user. The different spawn servers do not share
+memory with each other, so a lot of memory is wasted compared to the other
+methods.
+
+Implementing this will also take more work. One has to create a different
+wrapper for each user, and to install it.
+
+Using 'su'
+~~~~~~~~~~
+The standard Unix 'su' tool asks for the root password. It's a bad idea for
+Apache to know the root password, so using 'su' is not a viable alternative.
+
+Using 'sudo'
+~~~~~~~~~~~~
+It might be possible to use the 'sudo' utility. sudo can be configured in
+such a way that the user Apache runs as can use sudo without having to enter a
+password.
+
+However, Passenger uses an anonymous communication channel (an unnamed Unix
+socket) to communicate with the spawn server. sudo seems to close all file
+descriptors before executing an application, so Passenger will have to
+communicate with the spawn server via a non-anonymous channel, such as a named
+Unix socket. Because other processes can access this channel, it can introduce
+potential security problems. Note that passing information via program arguments
+is not secure: it is possible to view that information with tools like 'ps',
+or (on Linux) by reading the file `/proc/$PID/cmdline`.
+
+So it seems 'sudo' is not a viable alternative.
+
+Common security issues
+~~~~~~~~~~~~~~~~~~~~~~
+Whatever method Passenger will use, the following security principles must be
+honored:
+
+ - Rails applications must never be run as root.
+
+It might also be worthy to look into suEXEC's security model for inspiration.
+
+Also, the following questions remain:
+
+ - Is there a need for a user whitelist/blacklist? That is, is there a need for
+   the ability to restrict the set of users that Passenger can switch to?
+
+
+Chosen solution
+---------------
+Running Apache as root and writing a setuid root wrapper are the main
+contestants. The former is preferred, because it's easier to implement.
+
+We have had some conversations with people on the IRC channel #rubyonrails.
+Among those people, nobody has ever run Apache as non-root. Because of this
+we have chosen to implement the <<apache_root,Running Apache as root>>
+solution, until a significant number of users request us to implement the
+<<setuid_root,setuid root wrapper>> solution.
+
+Please read link:rdoc/index.html[the Ruby API documentation] -- in particular
+that of the 'ApplicationSpawner' class -- for implementation details. But to
+make a long story short: it will switch to the owner of the file
+'config/environment.rb'. User whitelisting/blacklisting is currently not
+implemented. We rely on the system administrator to set the correct owner
+on that file.
+
+We have also not implemented suEXEC's security model. suEXEC's model is quite
+paranoid, and although paranoia is good to a certain extend, it can be in the
+way of usability while proving little extra security. We are not entirely
+convinced that implementing suEXEC's full security model will provide
+significant benefits, but if you have good reasons to think otherwise, please
+feel free to discuss it with us.

data/doc/Users guide.html

@@ -0,0 +1,1356 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="generator" content="AsciiDoc 8.2.5" />
+<style type="text/css">
+/* Debug borders */
+p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
+/*
+  border: 1px solid red;
+*/
+}
+
+body {
+  margin: 1em 5% 1em 5%;
+}
+
+a {
+  color: blue;
+  text-decoration: underline;
+}
+a:visited {
+  color: fuchsia;
+}
+
+em {
+  font-style: italic;
+}
+
+strong {
+  font-weight: bold;
+}
+
+tt {
+  color: navy;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  color: #527bbd;
+  font-family: sans-serif;
+  margin-top: 1.2em;
+  margin-bottom: 0.5em;
+  line-height: 1.3;
+}
+
+h1, h2, h3 {
+  border-bottom: 2px solid silver;
+}
+h2 {
+  padding-top: 0.5em;
+}
+h3 {
+  float: left;
+}
+h3 + * {
+  clear: left;
+}
+
+div.sectionbody {
+  font-family: serif;
+  margin-left: 0;
+}
+
+hr {
+  border: 1px solid silver;
+}
+
+p {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+}
+
+pre {
+  padding: 0;
+  margin: 0;
+}
+
+span#author {
+  color: #527bbd;
+  font-family: sans-serif;
+  font-weight: bold;
+  font-size: 1.1em;
+}
+span#email {
+}
+span#revision {
+  font-family: sans-serif;
+}
+
+div#footer {
+  font-family: sans-serif;
+  font-size: small;
+  border-top: 2px solid silver;
+  padding-top: 0.5em;
+  margin-top: 4.0em;
+}
+div#footer-text {
+  float: left;
+  padding-bottom: 0.5em;
+}
+div#footer-badges {
+  float: right;
+  padding-bottom: 0.5em;
+}
+
+div#preamble,
+div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
+div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
+div.admonitionblock {
+  margin-right: 10%;
+  margin-top: 1.5em;
+  margin-bottom: 1.5em;
+}
+div.admonitionblock {
+  margin-top: 2.5em;
+  margin-bottom: 2.5em;
+}
+
+div.content { /* Block element content. */
+  padding: 0;
+}
+
+/* Block element titles. */
+div.title, caption.title {
+  font-family: sans-serif;
+  font-weight: bold;
+  text-align: left;
+  margin-top: 1.0em;
+  margin-bottom: 0.5em;
+}
+div.title + * {
+  margin-top: 0;
+}
+
+td div.title:first-child {
+  margin-top: 0.0em;
+}
+div.content div.title:first-child {
+  margin-top: 0.0em;
+}
+div.content + div.title {
+  margin-top: 0.0em;
+}
+
+div.sidebarblock > div.content {
+  background: #ffffee;
+  border: 1px solid silver;
+  padding: 0.5em;
+}
+
+div.listingblock {
+  margin-right: 0%;
+}
+div.listingblock > div.content {
+  border: 1px solid silver;
+  background: #f4f4f4;
+  padding: 0.5em;
+}
+
+div.quoteblock > div.content {
+  padding-left: 2.0em;
+}
+
+div.attribution {
+  text-align: right;
+}
+div.verseblock + div.attribution {
+  text-align: left;
+}
+
+div.admonitionblock .icon {
+  vertical-align: top;
+  font-size: 1.1em;
+  font-weight: bold;
+  text-decoration: underline;
+  color: #527bbd;
+  padding-right: 0.5em;
+}
+div.admonitionblock td.content {
+  padding-left: 0.5em;
+  border-left: 2px solid silver;
+}
+
+div.exampleblock > div.content {
+  border-left: 2px solid silver;
+  padding: 0.5em;
+}
+
+div.verseblock div.content {
+  white-space: pre;
+}
+
+div.imageblock div.content { padding-left: 0; }
+div.imageblock img { border: 1px solid silver; }
+span.image img { border-style: none; }
+
+dl {
+  margin-top: 0.8em;
+  margin-bottom: 0.8em;
+}
+dt {
+  margin-top: 0.5em;
+  margin-bottom: 0;
+  font-style: italic;
+}
+dd > *:first-child {
+  margin-top: 0;
+}
+
+ul, ol {
+    list-style-position: outside;
+}
+div.olist2 ol {
+  list-style-type: lower-alpha;
+}
+
+div.tableblock > table {
+  border: 3px solid #527bbd;
+}
+thead {
+  font-family: sans-serif;
+  font-weight: bold;
+}
+tfoot {
+  font-weight: bold;
+}
+
+div.hlist {
+  margin-top: 0.8em;
+  margin-bottom: 0.8em;
+}
+div.hlist td {
+  padding-bottom: 5px;
+}
+td.hlist1 {
+  vertical-align: top;
+  font-style: italic;
+  padding-right: 0.8em;
+}
+td.hlist2 {
+  vertical-align: top;
+}
+
+@media print {
+  div#footer-badges { display: none; }
+}
+
+div#toctitle {
+  color: #527bbd;
+  font-family: sans-serif;
+  font-size: 1.1em;
+  font-weight: bold;
+  margin-top: 1.0em;
+  margin-bottom: 0.1em;
+}
+
+div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
+  margin-top: 0;
+  margin-bottom: 0;
+}
+div.toclevel2 {
+  margin-left: 2em;
+  font-size: 0.9em;
+}
+div.toclevel3 {
+  margin-left: 4em;
+  font-size: 0.9em;
+}
+div.toclevel4 {
+  margin-left: 6em;
+  font-size: 0.9em;
+}
+/* Workarounds for IE6's broken and incomplete CSS2. */
+
+div.sidebar-content {
+  background: #ffffee;
+  border: 1px solid silver;
+  padding: 0.5em;
+}
+div.sidebar-title, div.image-title {
+  font-family: sans-serif;
+  font-weight: bold;
+  margin-top: 0.0em;
+  margin-bottom: 0.5em;
+}
+
+div.listingblock div.content {
+  border: 1px solid silver;
+  background: #f4f4f4;
+  padding: 0.5em;
+}
+
+div.quoteblock-content {
+  padding-left: 2.0em;
+}
+
+div.exampleblock-content {
+  border-left: 2px solid silver;
+  padding-left: 0.5em;
+}
+
+/* IE6 sets dynamically generated links as visited. */
+div#toc a:visited { color: blue; }
+</style>
+<script type="text/javascript">
+/*<![CDATA[*/
+window.onload = function(){generateToc(3)}
+/* Author: Mihai Bazon, September 2002
+ * http://students.infoiasi.ro/~mishoo
+ *
+ * Table Of Content generator
+ * Version: 0.4
+ *
+ * Feel free to use this script under the terms of the GNU General Public
+ * License, as long as you do not remove or alter this notice.
+ */
+
+ /* modified by Troy D. Hanson, September 2006. License: GPL */
+ /* modified by Stuart Rackham, October 2006. License: GPL */
+
+function getText(el) {
+  var text = "";
+  for (var i = el.firstChild; i != null; i = i.nextSibling) {
+    if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
+      text += i.data;
+    else if (i.firstChild != null)
+      text += getText(i);
+  }
+  return text;
+}
+
+function TocEntry(el, text, toclevel) {
+  this.element = el;
+  this.text = text;
+  this.toclevel = toclevel;
+}
+
+function tocEntries(el, toclevels) {
+  var result = new Array;
+  var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
+  // Function that scans the DOM tree for header elements (the DOM2
+  // nodeIterator API would be a better technique but not supported by all
+  // browsers).
+  var iterate = function (el) {
+    for (var i = el.firstChild; i != null; i = i.nextSibling) {
+      if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
+        var mo = re.exec(i.tagName)
+        if (mo)
+          result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
+        iterate(i);
+      }
+    }
+  }
+  iterate(el);
+  return result;
+}
+
+// This function does the work. toclevels = 1..4.
+function generateToc(toclevels) {
+  var toc = document.getElementById("toc");
+  var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);
+  for (var i = 0; i < entries.length; ++i) {
+    var entry = entries[i];
+    if (entry.element.id == "")
+      entry.element.id = "toc" + i;
+    var a = document.createElement("a");
+    a.href = "#" + entry.element.id;
+    a.appendChild(document.createTextNode(entry.text));
+    var div = document.createElement("div");
+    div.appendChild(a);
+    div.className = "toclevel" + entry.toclevel;
+    toc.appendChild(div);
+  }
+}
+/*]]>*/
+</script>
+<title>Passenger users guide</title>
+</head>
+<body>
+<div id="header">
+<h1>Passenger users guide</h1>
+<div id="toc">
+  <div id="toctitle">Table of Contents</div>
+  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
+</div>
+</div>
+<div id="preamble">
+<div class="sectionbody">
+<div class="para"><p><span class="image">
+<a class="image" href="http://www.phusion.nl/">
+<img src="images/phusion_banner.png" alt="images/phusion_banner.png" />
+</a>
+</span></p></div>
+<div class="para"><p>Passenger is an Apache module, which makes deploying Ruby on Rails applications
+on Apache a breeze. It follows the usual Ruby on Rails conventions, such as
+"Don't-Repeat-Yourself" and ease of setup.</p></div>
+<div class="para"><p>This users guide will teach you:</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+How to install Passenger.
+</p>
+</li>
+<li>
+<p>
+How to configure Passenger.
+</p>
+</li>
+<li>
+<p>
+How to deploy a Ruby on Rails application.
+</p>
+</li>
+<li>
+<p>
+How to solve common problems.
+</p>
+</li>
+</ul></div>
+<div class="para"><p>This guide assumes that the reader is somewhat familiar with Apache and with
+using the commandline.</p></div>
+</div>
+</div>
+<h2 id="_installation">1. Installation</h2>
+<div class="sectionbody">
+<h3 id="_supported_operating_systems">1.1. Supported operating systems</h3><div style="clear:left"></div>
+<div class="para"><p>Passenger works on any POSIX-compliant operating system. In other words:
+practically any operating system on earth, except Microsoft Windows.</p></div>
+<div class="para"><p>Passenger has been tested on:</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+Ubuntu Linux 6.06 (x86)
+</p>
+</li>
+<li>
+<p>
+Ubuntu Linux 7.10 (x86)
+</p>
+</li>
+<li>
+<p>
+Debian Sarge (x86)
+</p>
+</li>
+<li>
+<p>
+Debian Etch (x86)
+</p>
+</li>
+<li>
+<p>
+Debian Lenny/Sid (x86)
+</p>
+</li>
+<li>
+<p>
+CentOS 5 (x86)
+</p>
+</li>
+<li>
+<p>
+Red Hat Enterprise Linux 5 (x86)
+</p>
+</li>
+<li>
+<p>
+Gentoo, March 14 2008 (AMD64)
+</p>
+</li>
+<li>
+<p>
+FreeBSD 6.1-RELEASE (x86)
+</p>
+</li>
+<li>
+<p>
+MacOS X Tiger (x86)
+</p>
+</li>
+<li>
+<p>
+MacOS X Leopard (x86)
+</p>
+</li>
+</ul></div>
+<div class="para"><p>Other operating systems have not been tested, but Passenger will probably work
+fine on them. Please
+<a href="http://code.google.com/p/phusion-passenger/issues/list">report a bug</a>
+or
+<a href="http://groups.google.com/group/phusion-passenger">join our discussion list</a>
+if it doesn't.</p></div>
+<h3 id="install_passenger">1.2. Overview of download and installation methods</h3><div style="clear:left"></div>
+<div class="para"><p>There are two ways to install Passenger:</p></div>
+<div class="olist"><ol>
+<li>
+<p>
+By installing the Passenger gem, as instructed on the &#8220;Install&#8221; page
+   on the Passenger website.
+</p>
+</li>
+<li>
+<p>
+By downloading the source tarball from the Passenger website
+   (<em>passenger-x.x.x.tar.gz</em>).
+</p>
+</li>
+</ol></div>
+<div class="para"><p>In our opinion, installing the gem is easiest.</p></div>
+<div class="para"><p>Passenger provides an easy-to-use installer for installing the Passenger
+Apache module (<em>mod_passenger</em>).</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">You might have to run the installation commands in the following sections
+as <em>root</em>. If the installer fails because of permission errors, it will tell
+you.</td>
+</tr></table>
+</div>
+<h3 id="specifying_correct_apache_install">1.3. Specifying the correct Apache installation</h3><div style="clear:left"></div>
+<div class="para"><p>If your system has multiple Apache installations (this is likely the case on
+MacOS X), then you will need to tell the Passenger installer which one to use.
+If you only have one Apache installation (the case on most Linux systems), then
+you can skip this section because Passenger will automatically detect it.</p></div>
+<div class="para"><p>Every Apache installation has its own <tt>apxs</tt> program. You will need to tell
+Passenger the location of this program, by specifying the <tt>APXS2</tt> environment
+variable. Suppose that you want to use the Apache installation in
+<em>/opt/apache2</em>. Then, assuming that the corresponding <tt>apxs</tt> program is located
+<em>/opt/apache2/bin/apxs</em>, type:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>export APXS2=/opt/apache2/bin/apxs</tt></pre>
+</div></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">On some systems, the <tt>apxs</tt> program might be called <tt>apxs2</tt>, and it might
+be located in the <tt>sbin</tt> folder instead of the <tt>bin</tt> folder.</td>
+</tr></table>
+</div>
+<h3 id="specifying_ruby_installation">1.4. Specifying the correct Ruby installation</h3><div style="clear:left"></div>
+<div class="para"><p>If your system has multiple Ruby installations (this is likely the case on
+MacOS X), then you will need to tell the Passenger installer which one to use.
+If you only have one Ruby installation (the case on most Linux systems), then
+you can skip this section because Passenger will automatically detect it.</p></div>
+<div class="para"><p>To specify the Ruby installation, prepend your Ruby installation's <tt>bin</tt>
+directory to the <tt>PATH</tt> environment variable. For example, if you have the
+following Ruby installations:</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+/usr/bin/ruby
+</p>
+</li>
+<li>
+<p>
+/opt/myruby/bin/ruby
+</p>
+</li>
+</ul></div>
+<div class="para"><p>and you want to use the latter, then type:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>export PATH=/opt/myruby/bin:$PATH</tt></pre>
+</div></div>
+<h3 id="_installing_via_the_gem">1.5. Installing via the gem</h3><div style="clear:left"></div>
+<div class="para"><p>Please install the gem and then run the Passenger installer, by typing the
+following commands:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>gem install passenger-x.x.x.gem
+passenger-install-apache2-module</tt></pre>
+</div></div>
+<div class="para"><p>Please follow the instructions given by the installer.</p></div>
+<h3 id="_installing_via_the_source_tarball">1.6. Installing via the source tarball</h3><div style="clear:left"></div>
+<div class="para"><p>Extract the tarball to whatever location you prefer. The Passenger files
+are to reside in that location permanently. For example, if you would like
+Passenger to reside in <tt>/opt/passenger-x.x.x</tt>:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>cd /opt
+tar xzvf ~/YourDownloadsFolder/passenger-x.x.x.tar.gz</tt></pre>
+</div></div>
+<div class="para"><p>Next, run the included installer:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>/opt/passenger-x.x.x/bin/passenger-install-apache2-module</tt></pre>
+</div></div>
+<div class="para"><p>Please follow the instructions given by the installer.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/important.png" alt="Important" />
+</td>
+<td class="content">Please do not remove the <em>passenger-x.x.x</em> folder after
+installation. Furthermore, the <em>passenger-x.x.x</em> folder must be accessible by Apache.</td>
+</tr></table>
+</div>
+</div>
+<h2 id="_deploying_a_ruby_on_rails_application">2. Deploying a Ruby on Rails application</h2>
+<div class="sectionbody">
+<div class="para"><p>Suppose you have a Ruby on Rails application in <em>/webapps/mycook</em>, and you own
+the domain <em>www.mycook.com</em>. You can either deploy your application in the
+virtual host's root (i.e. the application will be accessible from the root URL,
+<em>http://www.mycook.com/</em>), or in a sub URI (i.e. the application will be
+accessible from a sub URL, such as <em>http://www.mycook.com/railsapplication</em>).</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">The default <tt>RAILS_ENV</tt> environment in which deployed Rails applications
+are run, is &#8220;production&#8221;. You can change this by changing the
+<a href="#rails_env"><em>RailsEnv</em></a> configuration option.</td>
+</tr></table>
+</div>
+<h3 id="_deploying_to_a_virtual_host_s_root">2.1. Deploying to a virtual host's root</h3><div style="clear:left"></div>
+<div class="para"><p>Add a virtual host entry to your Apache configuration file. The virtual host's
+document root must point to your Ruby on Rails application's <em>public</em> folder.
+For example:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>&lt;VirtualHost *:80&gt;
+    ServerName www.mycook.com
+    DocumentRoot /webapps/mycook/public
+&lt;/VirtualHost&gt;</tt></pre>
+</div></div>
+<div class="para"><p>Then restart Apache. The application has now been deployed.</p></div>
+<h3 id="deploying_to_sub_uri">2.2. Deploying to a sub URI</h3><div style="clear:left"></div>
+<div class="para"><p>Suppose that you already have a virtual host:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>&lt;VirtualHost *:80&gt;
+    ServerName www.phusion.nl
+    DocumentRoot /websites/phusion
+&lt;/VirtualHost&gt;</tt></pre>
+</div></div>
+<div class="para"><p>And you want your Ruby on Rails application to be accessible from the URL
+<em>http://www.phusion.nl/rails</em>.</p></div>
+<div class="para"><p>To do this, make a symlink from your Ruby on Rails application's <em>public</em>
+folder to a directory in the document root. For example:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>ln -s /webapps/mycook/public /websites/phusion/rails</tt></pre>
+</div></div>
+<div class="para"><p>Next, add a <tt>RailsBaseURI</tt> option to the virtual host configuration:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>&lt;VirtualHost *:80&gt;
+    ServerName www.phusion.nl
+    DocumentRoot /websites/phusion
+    RailsBaseURI /rails                # This line has been added.
+&lt;/VirtualHost&gt;</tt></pre>
+</div></div>
+<div class="para"><p>Then restart Apache. The application has now been deployed.</p></div>
+<h3 id="_redeploying_restarting_the_ruby_on_rails_application">2.3. Redeploying (restarting the Ruby on Rails application)</h3><div style="clear:left"></div>
+<div class="para"><p>Deploying a new version of a Ruby on Rails application is as simple as
+re-uploading the application files, and restarting the application.</p></div>
+<div class="para"><p>There are two ways to restart the application:</p></div>
+<div class="olist"><ol>
+<li>
+<p>
+By restarting Apache.
+</p>
+</li>
+<li>
+<p>
+By creating or modifying the file <em>tmp/restart.txt</em> in the Rails
+   application's root folder. Passenger will automatically restart the
+   application.
+</p>
+</li>
+</ol></div>
+<div class="para"><p>For example, to restart our example MyCook application, we type this in the
+command line:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>touch /webapps/mycook/tmp/restart.txt</tt></pre>
+</div></div>
+</div>
+<h2 id="_configuring_passenger">3. Configuring Passenger</h2>
+<div class="sectionbody">
+<div class="para"><p>After installation, Passenger does not need any further configurations.
+Nevertheless, the system administrator may be interested in changing
+Passenger's behavior. Passenger's Apache module supports the following
+configuration options:</p></div>
+<div class="vlist"><dl>
+<dt>
+RailsSpawnServer &lt;filename&gt;
+</dt>
+<dd>
+<p>
+        The location to the Passenger spawn server. This configuration option is
+        essential to Passenger. The correct value is given by the installer,
+        and should usually not be changed manually.
+</p>
+<div class="para"><p>This option may only occur once, in the global server configuration. If
+this option is not given, then Passenger will look for the program
+<tt>passenger-spawn-server</tt> in <tt>$PATH</tt>.</p></div>
+</dd>
+<dt>
+RailsBaseURI &lt;uri&gt;
+</dt>
+<dd>
+<p>
+        Used to specify that the given URI is a Rails application. See
+        <a href="#deploying_to_sub_uri">Deploying to a sub URI</a> for an example.
+</p>
+<div class="para"><p>This option may occur multiple times, in the global server configuration or in a
+virtual host configuration block.</p></div>
+</dd>
+<dt>
+RailsAutoDetect &lt;on|off&gt;
+</dt>
+<dd>
+<p>
+        Whether Passenger should automatically detect whether a virtual host's
+        document root is a Ruby on Rails application. The default is <em>on</em>.
+</p>
+<div class="para"><p>This option may occur in the global server configuration or in a virtual host
+configuration block.</p></div>
+<div class="para"><p>For example, consider the following configuration:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>RailsAutoDetect off
+&lt;VirtualHost *:80&gt;
+    ServerName www.mycook.com
+    DocumentRoot /webapps/mycook/public
+&lt;/VirtualHost&gt;</tt></pre>
+</div></div>
+<div class="para"><p>If one goes to <em>http://www.mycook.com/</em>, the visitor will see the contents of
+the <em>/webapps/mycook/public</em> folder, instead of the output of the Ruby on Rails
+application.</p></div>
+<div class="para"><p>It is possible to explicitly specify that the host is a Ruby on Rails
+application by using the <tt>RailsBaseURI</tt> configuration option:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>RailsAutoDetect off
+&lt;VirtualHost *:80&gt;
+    ServerName www.mycook.com
+    DocumentRoot /webapps/mycook/public
+    RailsBaseURI /
+&lt;/VirtualHost&gt;</tt></pre>
+</div></div>
+</dd>
+</dl></div>
+<div class="vlist" id="RailsAllowModRewrite"><dl>
+<dt>
+RailsAllowModRewrite &lt;on|off&gt;
+</dt>
+<dd>
+<p>
+        If enabled, Passenger will not override mod_rewrite rules. Please read
+        <a href="#conflicting_apache_modules">Conflicting Apache modules</a> for details.
+</p>
+<div class="para"><p>This option may occur in the global server configuration or in a virtual host
+configuration block. The default value is <em>off</em>.</p></div>
+</dd>
+<dt>
+RailsRuby &lt;filename&gt;
+</dt>
+<dd>
+<p>
+        This option allows one to specify the Ruby interpreter to use.
+</p>
+<div class="para"><p>This option may only occur once, in the global server configuration.
+The default is <em>ruby</em>.</p></div>
+</dd>
+</dl></div>
+<div class="vlist" id="rails_env"><dl>
+<dt>
+RailsEnv &lt;string&gt;
+</dt>
+<dd>
+<p>
+        This option allows one to specify the default <tt>RAILS_ENV</tt> value.
+</p>
+<div class="para"><p>This option may only occur once, in the global server configuration.
+The default is <em>production</em>.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/tip.png" alt="Tip" />
+</td>
+<td class="content">Even though it is not possible to specify a different RailsEnv
+per virtual host in the Apache configuration file, one can set the
+Rails environment by editing <tt>RAILS_ENV=&#8230;</tt> in the application's
+<em>config/environment.rb</em>.</td>
+</tr></table>
+</div>
+</dd>
+<dt>
+RailsMaxPoolSize &lt;integer&gt;
+</dt>
+<dd>
+<p>
+        The maximum number of Ruby on Rails application instances that may
+        be simultaneously active. A larger number results in higher memory usage,
+        but improved ability to handle concurrent HTTP clients.
+</p>
+<div class="para"><p>The optimal value depends on your system's hardware and the server's average
+load. You should experiment with different values. But generally speaking,
+the value should be at least equal to the number of CPUs (or CPU cores) that
+you have. If your system has 2 GB of RAM, then we recommend a value of <em>30</em>.
+If your system is a Virtual Private Server (VPS) and has about 256 MB RAM, and
+is also running other services such as MySQL, then we recommend a value of <em>2</em>.</p></div>
+<div class="para"><p>If you find that your server is unable to handle the load on your Rails websites
+(i.e. running out of memory) then you should lower this value. (Though if your
+sites are really that popular, then you should strongly consider upgrading your
+hardware or getting more servers.)</p></div>
+<div class="para"><p>This option may only occur once, in the global server configuration.
+The default value is <em>20</em>.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/tip.png" alt="Tip" />
+</td>
+<td class="content">We strongly recommend you to <a href="#reducing_memory_usage">use Ruby Enterprise Edition</a>. This allows you to reduce your memory usage by about 33%. And it's
+not hard to install.</td>
+</tr></table>
+</div>
+</dd>
+<dt>
+RailsPoolIdleTime &lt;integer&gt;
+</dt>
+<dd>
+<p>
+        The maximum number of seconds that a Ruby on Rails application instance
+        may be idle. That is, if an application instance hasn't done anything after
+        the given number of seconds, then it will be shutdown in order to conserve
+        memory.
+</p>
+<div class="para"><p>Decreasing this value means that Rails applications will have to be spawned
+more often. Since spawning is a relatively slow operation, some visitors may
+notice a small delay when they visit your Rails site. However, it will also
+free up resources used by Rails applications more quickly.</p></div>
+<div class="para"><p>The optimal value depends on the average time that a visitor spends on a single
+Rails web page. We recommend a value of <tt>2 * x</tt>, where <tt>x</tt> is the average
+number of seconds that a visitor spends on a single Rails web page. But your
+mileage may vary.</p></div>
+<div class="para"><p>This option may only occur once, in the global server configuration.
+The default value is <em>120</em>.</p></div>
+</dd>
+</dl></div>
+<div class="vlist" id="RailsUserSwitching"><dl>
+<dt>
+RailsUserSwitching &lt;on|off&gt;
+</dt>
+<dd>
+<p>
+        Whether to enable <a href="#user_switching">user switching support</a>.
+</p>
+<div class="para"><p>This option may only occur once, in the global server configuration.
+The default value is <em>on</em>.</p></div>
+</dd>
+</dl></div>
+<div class="vlist" id="RailsDefaultUser"><dl>
+<dt>
+RailsDefaultUser &lt;username&gt;
+</dt>
+<dd>
+<p>
+        Passenger enables <a href="#user_switching">user switching support</a> by default.
+        This configuration option allows one to specify which user Rails
+        applications must run as, if user switching fails or is disabled.
+</p>
+<div class="para"><p>This option may only occur once, in the global server configuration.
+The default value is <em>nobody</em>.</p></div>
+</dd>
+</dl></div>
+</div>
+<h2 id="_troubleshooting">4. Troubleshooting</h2>
+<div class="sectionbody">
+<h3 id="_problems_during_installation">4.1. Problems during installation</h3><div style="clear:left"></div>
+<h4 id="installing_ruby_dev">4.1.1. Ruby development headers aren't installed</h4>
+<div class="sidebarblock">
+<div class="sidebar-content">
+<div class="sidebar-title">Symptoms</div>
+<div class="para"><p>Installing Passenger fails because of one of the following errors:</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+The Passenger installer tells you that the Ruby development headers aren't
+  installed.
+</p>
+</li>
+<li>
+<p>
+The error message &#8220;<em>no such file to load &#8212; mkmf&#8221;</em> occurs.
+</p>
+</li>
+<li>
+<p>
+The error message &#8220;<em>ruby.h: No such file or directory&#8221;</em> occurs.
+</p>
+</li>
+</ul></div>
+</div></div>
+<div class="para"><p>Passenger makes use of a native extension, so the Ruby development headers
+must be installed. On most Linux systems, Ruby and the Ruby development headers
+are contained in separate packages, so having Ruby installed does not
+automatically imply having the development headers installed.</p></div>
+<div class="para"><p>Here's how you can install the development headers:</p></div>
+<div class="vlist"><dl>
+<dt>
+Ubuntu/Debian
+</dt>
+<dd>
+<p>
+        Please type:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>sudo apt-get install ruby1.8-dev</tt></pre>
+</div></div>
+</dd>
+<dt>
+Fedora/CentOS/RHEL
+</dt>
+<dd>
+<p>
+        Please type:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>su -c 'yum install ruby-devel'</tt></pre>
+</div></div>
+</dd>
+<dt>
+FreeBSD
+</dt>
+<dd>
+<p>
+        Please install Ruby from <em>ports</em> or with <tt>pkg_add</tt>. If that fails,
+        please install Ruby from source.
+</p>
+</dd>
+<dt>
+MacOS X
+</dt>
+<dd>
+<p>
+        Please install Ruby from source.
+</p>
+</dd>
+<dt>
+Other operating systems
+</dt>
+<dd>
+<p>
+        Please consult your operating system's native package database.
+        There should be a package containing the Ruby development headers.
+        If that fails, please install Ruby from source.
+</p>
+</dd>
+</dl></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">If you've installed a new Ruby version (i.e. your system now contains
+multiple Ruby installations), then you will need to tell Passenger which Ruby
+installation you want to use. Please read
+<a href="#specifying_ruby_installation">Specifying the correct Ruby installation</a>.</td>
+</tr></table>
+</div>
+<h4 id="_apache_development_headers_aren_t_installed">4.1.2. Apache development headers aren't installed</h4>
+<div class="sidebarblock">
+<div class="sidebar-content">
+<div class="sidebar-title">Symptoms</div>
+<div class="para"><p>Installing Passenger fails because of one of the following errors:</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+The installer says that the Apache development headers aren't installed.
+</p>
+</li>
+<li>
+<p>
+The error message &#8220;<em>httpd.h: No such file or directory&#8221;</em> occurs.
+</p>
+<div class="para"><p>(Instead of <em>httpd.h</em>, the message might also be <em>http_config.h</em> or something
+else similar to <em>http_*.h</em>.)</p></div>
+</li>
+</ul></div>
+</div></div>
+<div class="vlist"><dl>
+<dt>
+Ubuntu
+</dt>
+<dd>
+<p>
+        Please type:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>sudo apt-get install apache2-prefork-dev</tt></pre>
+</div></div>
+</dd>
+<dt>
+Debian
+</dt>
+<dd>
+<p>
+        Please type:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>sudo apt-get install apache2-dev</tt></pre>
+</div></div>
+</dd>
+<dt>
+Fedora/CentOS/RHEL
+</dt>
+<dd>
+<p>
+        Please type:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>su -c 'yum install httpd-devel'</tt></pre>
+</div></div>
+</dd>
+<dt>
+FreeBSD
+</dt>
+<dd>
+<p>
+        Please install Apache from <em>ports</em> or with <tt>pkg_add</tt>. If that fails,
+        please install Apache from source.
+</p>
+</dd>
+<dt>
+MacOS X
+</dt>
+<dd>
+<p>
+        Please install Apache from source.
+</p>
+</dd>
+<dt>
+Other operating systems
+</dt>
+<dd>
+<p>
+        Please consult your operating system's native package database.
+        There should be a package containing the Apache development headers.
+        If that fails, please install Apache from source.
+</p>
+</dd>
+</dl></div>
+<h4 id="_apr_development_headers_aren_t_installed">4.1.3. APR development headers aren't installed</h4>
+<div class="sidebarblock">
+<div class="sidebar-content">
+<div class="sidebar-title">Symptoms</div>
+<div class="para"><p>Installing Passenger fails because one of the following errors:</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+The installer tells you that APR development headers aren't installed.
+</p>
+</li>
+<li>
+<p>
+The error message &#8220;<em>apr_pools.h: No such file or directory&#8221;</em> occurs.
+</p>
+</li>
+<li>
+<p>
+The error message &#8220;<em>apr_strings.h: No such file or directory&#8221;</em> occurs.
+</p>
+</li>
+</ul></div>
+</div></div>
+<div class="vlist"><dl>
+<dt>
+Ubuntu
+</dt>
+<dd>
+<p>
+        Please type:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>sudo apt-get install libapr1-dev</tt></pre>
+</div></div>
+</dd>
+<dt>
+Debian
+</dt>
+<dd>
+<p>
+        Please type:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>sudo apt-get install libapr1-dev</tt></pre>
+</div></div>
+</dd>
+<dt>
+Fedora/CentOS/RHEL
+</dt>
+<dd>
+<p>
+        Please type:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>su -c 'yum install apr-devel'</tt></pre>
+</div></div>
+</dd>
+<dt>
+Other Linux distributions
+</dt>
+<dd>
+<p>
+        Please consult your distribution's package database. There should be a
+        package which provides APR development headers.
+</p>
+</dd>
+<dt>
+Other operating systems
+</dt>
+<dd>
+<p>
+        The APR development are bundled with Apache. If the APR headers aren't,
+        then it probably means that they have been removed after Apache's been
+        installed. Please reinstall Apache to get back the APR headers.
+</p>
+</dd>
+</dl></div>
+<h4 id="_passenger_is_using_the_wrong_apache_during_installation">4.1.4. Passenger is using the wrong Apache during installation</h4>
+<div class="para"><p>Please <a href="#specifying_correct_apache_install">Specifying the correct Apache installation</a>, and re-run the Passenger installer.</p></div>
+<h4 id="_passenger_is_using_the_wrong_ruby_during_installation">4.1.5. Passenger is using the wrong Ruby during installation</h4>
+<div class="para"><p>Please <a href="#specifying_ruby_installation">Specifying the correct Ruby installation</a>, and re-run the Passenger installer.</p></div>
+<h3 id="_problems_after_installation">4.2. Problems after installation</h3><div style="clear:left"></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/tip.png" alt="Tip" />
+</td>
+<td class="content">
+<div class="title">The golden tip: read your Apache error logs!</div>
+<div class="para"><p><em>mod_passenger</em> will write all errors to the Apache error log. So if
+you're experiencing post-installation problems, please look
+inside the Apache error logs. It will tell you what exactly went wrong.</p></div>
+</td>
+</tr></table>
+</div>
+<h4 id="_passenger_has_been_compiled_against_the_wrong_apache_installation">4.2.1. Passenger has been compiled against the wrong Apache installation</h4>
+<div class="sidebarblock">
+<div class="sidebar-content">
+<div class="sidebar-title">Symptoms</div>
+<div class="para"><p>Apache crashes during startup (after being daemonized). The Apache error log
+says &#8220;<em>seg fault or similar nasty error detected in the parent process&#8221;</em>.</p></div>
+</div></div>
+<div class="para"><p>This problem is most likely to occur on MacOS X. Most OS X users have multiple
+Apache installations on their system.</p></div>
+<div class="para"><p>To solve this problem, please <a href="#specifying_correct_apache_install">specify the correct Apache installation</a>, and <a href="#install_passenger">reinstall Passenger</a>.</p></div>
+<h4 id="_the_apache_error_log_says_that_the_spawn_manager_script_does_not_exist_or_that_it_does_not_have_permission_to_execute_it">4.2.2. The Apache error log says that the spawn manager script does not exist, or that it does not have permission to execute it</h4>
+<div class="para"><p>If you are sure that the RailsSpawnServer configuration option is set correctly,
+then this problem is most likely caused by the fact that you're running Apache
+with SELinux. On Fedora, CentOS and RedHat Enterprise Linux, Apache is locked
+down by SELinux policies.</p></div>
+<div class="para"><p>To solve this problem, you must set some permissions on the Passenger files and
+folders, so that Apache can access them.</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+If you've installed Passenger via a gem, then you must first find out the
+  location in which RubyGems stores gem files. Type the following command:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>gem environment | grep 'INSTALLATION DIRECTORY'</tt></pre>
+</div></div>
+<div class="para"><p>It should show something along the lines of:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>  - INSTALLATION DIRECTORY: /usr/lib/ruby/gems/1.8</tt></pre>
+</div></div>
+<div class="para"><p>The directory name that you see in the output is the RubyGems gem folder.
+Next, we'll fix the Passenger folder permissions as follows:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>cd /usr/lib/ruby/gems/1.8     # Replace this with whatever your gem folder is.
+cd gems
+chcon -R -h -t httpd_sys_content_t passenger-*</tt></pre>
+</div></div>
+</li>
+<li>
+<p>
+If you've installed Passenger via the source tarball, then run the following
+  command:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>chcon -R -h -t httpd_sys_content_t /path/to/passenger/folder</tt></pre>
+</div></div>
+</li>
+</ul></div>
+<div class="para"><p>Once the permissions are fixed, restart Apache.</p></div>
+<h3 id="_the_rails_application_reports_that_it_s_unable_to_start_because_of_a_permission_error">4.3. The Rails application reports that it's unable to start because of a permission error</h3><div style="clear:left"></div>
+<div class="para"><p>Please check whether your Rails application's folder has the correct
+permissions. By default, Rails applications are started as the owner of the
+file <em>config/environment.rb</em>, except if the file is owned by root. If the
+file is owned by root, then the Rails application will be started as <em>nobody</em>
+(or as the user specify by <a href="#RailsDefaultUser">RailsDefaultUser</a>, if that's
+specified).</p></div>
+<div class="para"><p>Please read <a href="#user_switching">User switching (security)</a> for details.</p></div>
+</div>
+<h2 id="_tips_and_notes">5. Tips and notes</h2>
+<div class="sectionbody">
+<h3 id="user_switching">5.1. User switching (security)</h3><div style="clear:left"></div>
+<div class="para"><p>There is a problem that plagues most PHP web host, namely the fact that all PHP
+applications are run in the same user context as the web server. So for
+example, Joe's PHP application will be able to read Jane's PHP application's
+passwords. This is obviously undesirable on many servers.</p></div>
+<div class="para"><p>Passenger solves this problem by implementing <em>user switching</em>. A Rails
+application is started as the owner of the file <em>config/environment.rb</em>. So if
+<em>/home/webapps/foo/config/environment.rb</em> is owned by <em>joe</em>, then Passenger
+will launch the corresponding Rails application as <em>joe</em> as well.</p></div>
+<div class="para"><p>This behavior is the default, and you don't need to configure anything. But
+there are things that you should keep in mind:</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+The owner of <em>environment.rb</em> must have read access to the Rails application's
+  folder, and read/write access to the Rails application's <em>logs</em> folder.
+</p>
+</li>
+<li>
+<p>
+This feature is only available if Apache is started by <em>root</em>. This is the
+  case on most Apache installations.
+</p>
+</li>
+<li>
+<p>
+Under no circumstances will Rails applications be run as <em>root</em>. If
+  <em>environment.rb</em> is owned as root or by an unknown user, then the Rails
+  application will run as the user specified by
+  <a href="#RailsDefaultUser">RailsDefaultUser</a>.
+</p>
+</li>
+</ul></div>
+<div class="para"><p>User switching can be disabled with the
+<a href="#RailsUserSwitching">RailsUserSwitching</a> option.</p></div>
+<h3 id="reducing_memory_usage">5.2. Reducing memory consumption of Ruby on Rails apps by 33%</h3><div style="clear:left"></div>
+<div class="para"><p>Is it possible to reduce memory consumption of your Rails apps by 33% on average,
+by using <a href="http://www.rubyenterpriseedition.com/">Ruby Enterprise Edition</a>.
+Please visit the website for details.</p></div>
+<h3 id="_moving_passenger_to_a_different_directory">5.3. Moving Passenger to a different directory</h3><div style="clear:left"></div>
+<div class="para"><p>It is possible to relocate the Passenger files to a different directory. It
+involves two steps:</p></div>
+<div class="olist"><ol>
+<li>
+<p>
+Moving the directory.
+</p>
+</li>
+<li>
+<p>
+Updating the &#8220;RailsSpawnServer&#8221; configuration option in Apache.
+</p>
+</li>
+</ol></div>
+<div class="para"><p>For example, if Passenger is located in <em>/opt/passenger/</em>, and you'd like to
+move it to <em>/usr/local/passenger/</em>, then do this:</p></div>
+<div class="olist"><ol>
+<li>
+<p>
+Run the following command:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>mv /opt/passenger /usr/local/passenger</tt></pre>
+</div></div>
+</li>
+<li>
+<p>
+Edit your Apache configuration file, and set:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>RailsSpawnServer /usr/local/passenger/bin/passenger-spawn-server</tt></pre>
+</div></div>
+</li>
+</ol></div>
+<h3 id="_installing_multiple_ruby_on_rails_versions">5.4. Installing multiple Ruby on Rails versions</h3><div style="clear:left"></div>
+<div class="para"><p>Each Ruby on Rails applications that are going to be deployed may require a
+specific Ruby on Rails version. You can install a specific version with
+this command:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>gem install rails -v X.X.X</tt></pre>
+</div></div>
+<div class="para"><p>where <em>X.X.X</em> is the version number of Ruby on Rails.</p></div>
+<div class="para"><p>All of these versions will exist in parallel, and will not conflict with each
+other. Passenger will automatically make use of the correct version.</p></div>
+<h3 id="_x_sendfile_support">5.5. X-Sendfile support</h3><div style="clear:left"></div>
+<div class="para"><p>Passenger does not provide X-Sendfile support by itself. Please install
+<a href="http://tn123.ath.cx/mod_xsendfile/">mod_xsendfile</a> for X-Sendfile support.</p></div>
+<h3 id="conflicting_apache_modules">5.6. Conflicting Apache modules</h3><div style="clear:left"></div>
+<div class="para"><p>Passenger conflicts with <em>mod_rewrite</em> and <em>mod_alias</em>. Those modules may be
+installed and loaded together with <em>mod_passenger</em>, and they will work fine
+outside virtual hosts that contain a Rails application, but we recommend you
+not to use their features inside virtual hosts that contain a Rails
+application.</p></div>
+<div class="para"><p>By default, Passenger will override mod_rewrite rules on Rails hosts. This is
+because the default .htaccess, as provided by Ruby on Rails, redirects all
+requests to `dispatch.cgi' using mod_rewrite. This is a CGI application which
+loads the entire Ruby on Rails framework for every request, and thus is very
+slow. If we do not override mod_rewrite, then Ruby on Rails apps will be slow
+on Passenger by default &#8212; but we want a good out-of-the-box experience.</p></div>
+<div class="para"><p>Furthermore, the primary reason why people use mod_rewrite with Rails
+applications, is to accelerate page caching. Passenger supports page caching
+out-of-the-box, without mod_rewrite.</p></div>
+<div class="para"><p>It is not fully understood how mod_alias conflicts with Passenger, but we
+recommend you not to use it on Rails virtual hosts. mod_alias rules can result
+in surprising problems.</p></div>
+<div class="para"><p>If you really want to use mod_rewrite on Rails virtual hosts, then please set
+the <a href="#RailsAllowModRewrite">RailsAllowModRewrite</a> configuration option. But
+please note that you will have to delete Rails applications' default .htaccess
+file, or add rewrite rules to negate its effects.</p></div>
+</div>
+<h2 id="_appendix_a_about_this_document">6. Appendix A: About this document</h2>
+<div class="sectionbody">
+<div class="para"><p>The text of this document is licensed under the
+<a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons
+Attribution-Share Alike 3.0 Unported License</a>.</p></div>
+<div class="para"><p><span class="image">
+<a class="image" href="http://creativecommons.org/licenses/by-sa/3.0/">
+<img src="images/by_sa.png" alt="images/by_sa.png" />
+</a>
+</span></p></div>
+<div class="para"><p>Passenger is brought to you by Phusion.</p></div>
+<div class="para"><p><span class="image">
+<a class="image" href="http://www.phusion.nl/">
+<img src="images/phusion_banner.png" alt="images/phusion_banner.png" />
+</a>
+</span></p></div>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2008-04-10 21:31:28 CEST
+</div>
+</div>
+</body>
+</html>