Configuration reference

Relevant selection for this article:

Table of contents

1. Loading...

Application loading

PassengerRoot

Refers to the location to the Passenger root directory, or to a location configuration file. This configuration option is essential to Passenger, and allows Passenger to locate its own data files.

You normally do not need to set this configuration option. If you used our Debian or RPM packages to install Passenger, then they automatically configure PassengerRoot for you with the right value. If you installed Passenger from Homebrew, tarball or RubyGems, then at some point during the installation process you are told what the correct value should be, and instructed to insert it into your Apache configuration file.

What happens if this option is not set, or set wrongly

If you do not set PassengerRoot, then Passenger will complain about it and prevent Apache from starting.

If you set PassengerRoot to the wrong value, then Passenger will attempt to locate some of its own files, fail to do so, then complain with an error message and abort Apache.

How to fix PassengerRoot

If you lost the PassengerRoot configuration value (e.g. because you accidentally removed the Apache configuration file, and you are trying to reconstruct it), if you didn't follow the installation instructions correctly, or if you moved Passenger to a different directory, then you can fix PassengerRoot as follows:

• If you installed Passenger through source tarball or by cloning it from the Passenger Github repository, then the value should be the path to the Passenger directory.
• In all other cases, obtain the correct value by running the following command:

passenger-config –root

Once you have obtained the value, open your Apache configuration file and insert a PassengerRoot option somewhere with that value.

PassengerDefaultRuby

This option specifies:

• which Ruby interpreter Passenger should use for its internal Ruby helper tools, e.g. the one used by PassengerPreStart. See Lightweight Ruby dependency for more information.
• the default Ruby interpreter to use for Ruby web apps. Naturally, this is not applicable if you do not use Passenger to serve Ruby web apps. Please see PassengerRuby for more information, as well as how it relates to PassengerDefaultRuby.

The default value is ruby, meaning that the Ruby interpreter will be looked up according to the PATH environment variable.

If you want to specify the Ruby interpreter to use for serving a specific Ruby web application, then we recommend that you use the PassengerRuby configuration option instead of PassengerDefaultRuby. While PassengerDefaultRuby specifies a default value for PassengerRuby, the main reason why PassengerDefaultRuby exists is to specify which Ruby interpreter to use for internal Ruby helper tools.

If you installed Passenger through source tarball or RubyGems, then you should know that it is okay if PassengerDefaultRuby refers to a different Ruby interpreter than the one you used originally installed Passenger with. Please learn more at How having multiple Ruby interpreters affects Passenger.

PassengerEnabled

This option enables or disables Passenger for that particular context. Passenger is enabled by default. You can set this option to off to completely disable Passenger for that context. This option is useful if, for example, you want a certain location to be handled by a different Apache module, not by Passenger.

Example

Suppose that you have a Ruby application in /apps/foo. Suppose that you've dropped Wordpress – a blogging application written in PHP – in /apps/foo/public/wordpress. You'll need to configure Passenger as follows, so that Passenger doesn't interfere with the Wordpress installation:

<VirtualHost *:80>
    ServerName www.foo.com
    DocumentRoot /apps/foo/public
    <Directory /apps/foo/public/wordpress>
        PassengerEnabled off
    # Makes Wordpress's .htaccess file work
        AllowOverride all
    </Directory>
</VirtualHost>

PassengerStartTimeout

Specifies a timeout for the startup of application processes. If an application process fails to start within the timeout period then it will be forcefully killed with SIGKILL, and the error will be logged.

PassengerRuby

The PassengerRuby option specifies the Ruby interpreter to use for serving Ruby web applications. If PassengerRuby is not specified, then it defaults to the value of PassengerDefaultRuby (which in itself defaults to ruby, meaning the first ruby command found in PATH).

Closely related to PassengerRuby is PassengerPython, PassengerNodejs, etc. The following example illustrates how it works and how you can use these options to specify different interpreters for different web apps.

# Use Ruby 2.1 by default.
PassengerDefaultRuby /usr/bin/ruby2.1
# Use Python 2.6 by default.
PassengerPython /usr/bin/python2.6
# Use /usr/bin/node by default.
PassengerNodejs /usr/bin/node

<VirtualHost *:80>
    # This Ruby web app will use Ruby 2.1
    ServerName www.foo.com
    DocumentRoot /webapps/foo/public
</VirtualHost>

<VirtualHost *:80>
    # This Rails web app will use Ruby 2.2.1, as installed by RVM
    PassengerRuby /usr/local/rvm/wrappers/ruby-2.2.1/ruby
    ServerName www.bar.com
    DocumentRoot /webapps/bar/public

    # If you have a web app deployed in a sub-URI, customize
    # PassengerRuby/PassengerPython inside a <Location> block.
    # The web app under www.bar.com/blog will use JRuby 1.7.1
    Alias /blog /websites/blog/public
    <Location /blog>
        PassengerBaseURI /blog
        PassengerAppRoot /websites/blog

        PassengerRuby /usr/local/rvm/wrappers/jruby-1.7.1/ruby
    </Location>
    <Directory /websites/blog/public>
        Allow from all
        Options -MultiViews
        # Uncomment this if you're on Apache ≥ 2.4:
        #Require all granted
    </Directory>
</VirtualHost>

<VirtualHost *:80>
    # This Flask web app will use Python 3.0
    PassengerPython /usr/bin/python3.0
    ServerName www.baz.com
    DocumentRoot /webapps/baz/public
</VirtualHost>

Notes about multiple Ruby interpreters

If your system has multiple Ruby interpreters, then it is important that you set this configuration option to the right value. If you do not set this configuration option correctly, and your app is run under the wrong Ruby interpreter, then all sorts of things may go wrong, such as:

• The app won't be able to find its installed gems.
• The app won't be able to run because of syntax and feature differences between Ruby versions.

Note that a different RVM gemset also counts as "a different Ruby interpreter".

How to set the correct value

If you are not sure what value to set PassengerRuby to, then you can find out the correct value as follows.

First, find out the location to the passenger-config tool and take note of it:

$ which passenger-config
/opt/passenger/bin/passenger-config

Next, activate the Ruby interpreter (and if applicable, the gemset) you want to use. For example, if you are on RVM and you use Ruby 2.2.1, you may want to run this:

$ rvm use 2.2.1

Finally, invoke passenger-config with its full path, passing --ruby-command as parameter:

$ /opt/passenger/bin/passenger-config --ruby-command
passenger-config was invoked through the following Ruby interpreter:
  Command: /usr/local/rvm/wrappers/ruby-1.8.7-p358/ruby
  Version: ruby 1.8.7 (2012-02-08 patchlevel 358) [universal-darwin12.0]
  To use in Apache: PassengerRuby /usr/local/rvm/wrappers/ruby-1.8.7-p358/ruby
  To use in Nginx : passenger_ruby /usr/local/rvm/wrappers/ruby-1.8.7-p358/ruby
  To use with Standalone: /usr/local/rvm/wrappers/ruby-1.8.7-p358/ruby /opt/passenger/bin/passenger start


## Notes for RVM users
Do you want to know which command to use for a different Ruby interpreter? 'rvm use' that Ruby interpreter, then re-run 'passenger-config --ruby-command'.

The output tells you what value to set.

PassengerPython

This option specifies the Python interpreter to use for serving Python web applications. If it is not specified, then it uses the first python command found in PATH.

Closely related to this option is PassengerRuby, PassengerNodejs, etc. The following example illustrates how it works and how you can use these options to specify different interpreters for different web apps.

# Use Ruby 2.1 by default.
PassengerDefaultRuby /usr/bin/ruby2.1
# Use Python 2.6 by default.
PassengerPython /usr/bin/python2.6
# Use /usr/bin/node by default.
PassengerNodejs /usr/bin/node

<VirtualHost *:80>
    # This Ruby web app will use Ruby 2.1
    ServerName www.foo.com
    DocumentRoot /webapps/foo/public
</VirtualHost>

<VirtualHost *:80>
    # This Rails web app will use Ruby 2.2.1, as installed by RVM
    PassengerRuby /usr/local/rvm/wrappers/ruby-2.2.1/ruby
    ServerName www.bar.com
    DocumentRoot /webapps/bar/public

    # If you have a web app deployed in a sub-URI, customize
    # PassengerRuby/PassengerPython inside a <Location> block.
    # The web app under www.bar.com/blog will use JRuby 1.7.1
    Alias /blog /websites/blog/public
    <Location /blog>
        PassengerBaseURI /blog
        PassengerAppRoot /websites/blog

        PassengerRuby /usr/local/rvm/wrappers/jruby-1.7.1/ruby
    </Location>
    <Directory /websites/blog/public>
        Allow from all
        Options -MultiViews
        # Uncomment this if you're on Apache ≥ 2.4:
        #Require all granted
    </Directory>
</VirtualHost>

<VirtualHost *:80>
    # This Flask web app will use Python 3.0
    PassengerPython /usr/bin/python3.0
    ServerName www.baz.com
    DocumentRoot /webapps/baz/public
</VirtualHost>

PassengerNodejs

This option specifies the Node.js command to use for serving Node.js web applications. If it is not specified, then it uses the first node command found in PATH.

Closely related to this option is PassengerRuby, PassengerPython, etc. The following example illustrates how it works and how you can use these options to specify different interpreters for different web apps.

# Use Ruby 2.1 by default.
PassengerDefaultRuby /usr/bin/ruby2.1
# Use Python 2.6 by default.
PassengerPython /usr/bin/python2.6
# Use /usr/bin/node by default.
PassengerNodejs /usr/bin/node

<VirtualHost *:80>
    # This Ruby web app will use Ruby 2.1
    ServerName www.foo.com
    DocumentRoot /webapps/foo/public
</VirtualHost>

<VirtualHost *:80>
    # This Rails web app will use Ruby 2.2.1, as installed by RVM
    PassengerRuby /usr/local/rvm/wrappers/ruby-2.2.1/ruby
    ServerName www.bar.com
    DocumentRoot /webapps/bar/public

    # If you have a web app deployed in a sub-URI, customize
    # PassengerRuby/PassengerPython inside a <Location> block.
    # The web app under www.bar.com/blog will use JRuby 1.7.1
    Alias /blog /websites/blog/public
    <Location /blog>
        PassengerBaseURI /blog
        PassengerAppRoot /websites/blog

        PassengerRuby /usr/local/rvm/wrappers/jruby-1.7.1/ruby
    </Location>
    <Directory /websites/blog/public>
        Allow from all
        Options -MultiViews
        # Uncomment this if you're on Apache ≥ 2.4:
        #Require all granted
    </Directory>
</VirtualHost>

<VirtualHost *:80>
    # This Flask web app will use Python 3.0
    PassengerPython /usr/bin/python3.0
    ServerName www.baz.com
    DocumentRoot /webapps/baz/public
</VirtualHost>

PassengerMeteorAppSettings

When using a Meteor application in non-bundled mode, use this option to specify a JSON file with settings for the application. The meteor run command will be run with the --settings parameter set to this option.

Note that this option is not intended to be used for bundled/packaged Meteor applications. When running bundled/packaged Meteor applications on Passenger, you should set the METEOR_SETTINGS environment variable using SetEnv.

PassengerAppEnv

This option sets, for the current application, the value of the following environment variables:

• RAILS_ENV
• RACK_ENV
• WSGI_ENV
• NODE_ENV
• PASSENGER_APP_ENV

Some web frameworks, for example Rails and Connect.js, adjust their behavior according to the value in one of these environment variables.

Passenger sets the default value to production. If you're developing the application (instead of running it in production), then you should set this to development.

If you want to set other environment variables, please use SetEnv.

Setting this option also adds the application environment name to the default application group name, so that you can run multiple versions of your application with different application environment names.

RailsEnv, RackEnv

These are aliases for PassengerAppEnv.

PassengerAppRoot

By default, Passenger assumes that the application's root directory is the parent directory of the DocumentRoot. This option allows one to the application's root independently from the DocumentRoot, which is useful if your application does not follow the conventions that Passenger assumes.

See also How Passenger + Apache autodetects applications.

Example

<VirtualHost test.host>
    DocumentRoot /var/rails/zena/sites/example.com/public
    # Normally Passenger would have assumed that the
      # application root is "/var/rails/zena/sites/example.com".
      # This overrides it.
    PassengerAppRoot /var/rails/zena
</VirtualHost>

PassengerAppGroupName

Sets the name of the application group that the current application should belong to. Its default value is the application root, plus (if it is explicitly set), the application environment name.

Passenger stores and caches most application spawning settings – such as environment variables, process limits, etc – on a per-app-group-name basis. This means that if you want to start two versions of your application, with each version having different environment variables, then you must assign them under different application group names.

The request queue is also per-application group, so creating multiple application groups allow you to separate requests into different queues.

Example

Consider a situation in which you are running multiple versions of the same app, with each version intended for a different customer. You use the CUSTOMER_NAME environment variable to tell the app which customer that version should serve.

# WRONG example! Doesn't work!

<VirtualHost *:80>
    ServerName customer1.foo.com
    DocumentRoot /webapps/foo/public
    SetEnv CUSTOMER_NAME customer1
</VirtualHost>

<VirtualHost *:80>
    ServerName customer2.foo.com
    DocumentRoot /webapps/foo/public
    SetEnv CUSTOMER_NAME customer2
</VirtualHost>

This example doesn't work, because Passenger thinks that they are the same application. When a user visits customer1.foo.com, Passenger will start a process with CUSTOMER_NAME=customer1. When another user visits customer2.foo.com, Passenger will route the request to the application process that was started earlier. Because environment variables are only set during application process startup, the second user will be served the website for customer 1.

To make this work, assign unique application group names:

<VirtualHost *:80>
  ServerName customer1.foo.com
  DocumentRoot /webapps/foo/public
  SetEnv CUSTOMER_NAME customer1
  PassengerAppGroupName foo_customer1
</VirtualHost>

<VirtualHost *:80>
  ServerName customer2.foo.com
  DocumentRoot /webapps/foo/public
  SetEnv CUSTOMER_NAME customer2
  PassengerAppGroupName foo_customer2
</VirtualHost>

Note that it is not necessary to set PassengerAppGroupName if you want to run two versions of your application under different application environment names, because the application environment name is included in the default application group name. For example, consider a situation in which you want to run a production and a staging version of your application. The following configuration will work fine:

<VirtualHost *:80>
    ServerName bar.com
    DocumentRoot /webapps/bar/public
    # Passenger implicitly sets:
      # PassengerAppGroupName /webapps/bar
</VirtualHost>

<VirtualHost *:80>
    ServerName staging.bar.com
    DocumentRoot /webapps/bar/public
    PassengerAppEnv staging
    # Passenger implicitly sets:
      # PassengerAppGroupName '/webapps/bar (staging)'
</VirtualHost>

PassengerAppStartCommand

Specifies how Passenger should start your app on a specific port.

Passenger has built-in support for starting Ruby, Python, Node.js, and Meteor apps, however it can also start any application written in any language which can listen on a specified port. This functionality is termed Generic Language Support (GLS) and is discussed in greater detail here. The minimum required configuration to make use of GLS in Passenger, is to specify how Passenger should start your app on a specific port. To achieve this you specify the PassengerAppStartCommand which is the command you would use on the command line to start your app, with a placeholder $PORT where Passenger should substitute its chosen port, for your app to receive and bind to. We go into greater detail on various ways to pass the port to your app if it doesn't take a command line argument to set the port here.

Consider the following config snippet:

PassengerAppStartCommand "/usr/local/bin/myapp --foreground --port $PORT"

Passenger will start your app by calling your command, with an actual port number in place of the $PORT placeholder. For eg. /usr/local/bin/myapp --foreground --port 5000.

PassengerAppType

By default, Passenger autodetects the type of the application, e.g. whether it's a Ruby, Python, Node.js or Meteor app. If it's unable to autodetect the type of the application (e.g. because you've specified a custom PassengerStartupFile) then you can use this option to force Passenger to recognize the application as a specific type.

Allowed values are:

If you set this option, then you must also set PassengerAppRoot, otherwise Passenger will not properly recognize your application.

Example

<VirtualHost test.host>
    DocumentRoot /webapps/example.com/public
    # Use server.js as the startup file (entry point file) for
      # your Node.js application, instead of the default app.js
    PassengerStartupFile server.js
    PassengerAppType node
    PassengerAppRoot /webapps/example.com
</VirtualHost>

PassengerStartupFile

This option specifies the startup file that Passenger should use when loading the application. This path is relative to the application root.

Every application has a startup file or entry point file: a file where the application begins execution. Some languages have widely accepted conventions about how such a file should be called (e.g. Ruby, with its config.ru). Other languages have somewhat-accepted conventions (e.g. Node.js, with its app.js). In these cases, Passenger follows these conventions, and executes applications through those files.

Other languages have no conventions at all, and so Passenger invents one (e.g. Python WSGI with passenger_wsgi.py).

Passenger tries to autodetect according to the following language-specific conventions:

For other cases you will need to specify the startup-file manually. For example, on Node.js, you might need to use bin/www as the startup file instead if you are using the Express app generator.

Notes

• Customizing the startup file affects user account sandboxing. After all, if user account sandboxing is enabled, the application is executed as the user that owns the startup file.
• If you set this option, you must also set PassengerAppRoot and PassengerAppType, otherwise Passenger doesn't know what kind of application it is.

Example

<VirtualHost test.host>
    DocumentRoot /webapps/example.com/public
    # Use server.js as the startup file (entry point file) for
      # your Node.js application, instead of the default app.js
    PassengerStartupFile server.js
    PassengerAppType node
    PassengerAppRoot /webapps/example.com
</VirtualHost>

PassengerRestartDir

As described in Restarting applications, Passenger checks the file tmp/restart.txt in the application root directory to determine whether it should restart the application. Sometimes it may be desirable for Passenger to look in a different directory instead, for example for security reasons (see below). This option allows you to customize the directory in which restart.txt is searched for.

You can either set it to an absolute directory, or to a directory relative to the application root.

Examples

<VirtualHost *:80>
    ServerName www.foo.com
    # Passenger will check for /apps/foo/public/tmp/restart.txt
    DocumentRoot /apps/foo/public
</VirtualHost>

<VirtualHost *:80>
    ServerName www.bar.com
    DocumentRoot /apps/bar/public
    # An absolute filename is given; Passenger will
      # check for /restart_files/bar/restart.txt
    PassengerRestartDir /restart_files/bar
</VirtualHost>

<VirtualHost *:80>
    ServerName www.baz.com
    DocumentRoot /apps/baz/public
    # A relative filename is given; Passenger will
      # check for /apps/baz/restart_files/restart.txt
      #
      # Note that this directory is relative to the APPLICATION ROOT, *not*
      # the value of DocumentRoot!
    PassengerRestartDir restart_files
</VirtualHost>

Security reasons for wanting to customize PassengerRestartDir

Touching restart.txt will cause Passenger to restart the application. So anybody who can touch restart.txt can effectively cause a Denial-of-Service attack by touching restart.txt over and over. If your web server or one of your web applications has the permission to touch restart.txt, and one of them has a security flaw which allows an attacker to touch restart.txt, then that will allow the attacker to cause a Denial-of-Service.

You can prevent this from happening by pointing PassengerRestartDir to a directory that's readable by Apache, but only writable by administrators.

PassengerSpawnMethod

This option controls whether Passenger spawns applications directly, or using a prefork copy-on-write mechanism. The spawn methods guide explains this in detail.

PassengerLoadShellEnvvars

Enables or disables the loading of shell environment variables before spawning the application.

If this option is turned on, and the user's shell is bash, then applications are loaded by running them with bash -l -c. The benefit of this is that you can specify environment variables in .bashrc, and they will appear in the application as one would expect.

If this option is turned off, applications are loaded by running them directly from the Passenger core process.

PassengerPreloadBundler

Enables or disables loading bundler before loading your Ruby app.

If this option is turned on, Ruby will be instructed to load the bundler gem before loading your application. This can help with gem version conflicts due to order-of require issues.

PassengerRollingRestarts

Enables or disables support for zero-downtime application restarts through restart.txt.

Please note that PassengerRollingRestarts is completely unrelated to the passenger-config restart-app command. That command always initiates a blocking restart, unless --rolling-restart is given.

NOTE: Are you looking to prevent applications from being restarted when you restart Apache? That is handled by the Flying Passenger mode, not by the rolling restarts feature.

PassengerResistDeploymentErrors

Enables or disables resistance against deployment errors.

Suppose that you have upgraded your application and you have issued a command to restart it, but the application update contains an error (e.g. a syntax error or a database configuration error) that prevents Passenger from successfully spawning a process. Passenger would normally display an error message to the visitor in response to this.

By enabling deployment error resistance, Passenger Enterprise would "freeze" the application's process list. Existing application processes (belonging to the previous version) will be kept around to serve requests. The error is logged, but visitors do not see any error messages. Passenger keeps the old processes around until an administrator has taken action. This way, visitors will suffer minimally from deployment errors.

Learn more about this feature in Deployment Error Resistance guide.

Note that enabling deployment error resistance only works if you perform a rolling restart instead of a blocking restart.

PassengerInstanceRegistryDir

Specifies the directory that Passenger should use for registering its current instance.

When Passenger starts up, it creates a temporary directory inside the instance registry directory. This temporary directory is called the instance directory. It contains all sorts of files that are important to that specific running Passenger instance, such as Unix domain socket files so that all the different Passenger processes can communicate with each other. Command line tools such as passenger-status use the files in this directory in order to query Passenger's status.

It is therefore important that, while Passenger is working, the instance directory is never removed or tampered with. However, the default path for the instance registry directory is the system's temporary directory, and some systems may run background jobs that periodically clean this directory. If this happens, and the files inside the instance directory are removed, then it will cause Passenger to malfunction: Passenger won't be able to communicate with its own processes, and you will see all kinds of connection errors in the log files. This malfunction can only be recovered from by restarting Apache. You can prevent such cleaning background jobs from interfering by setting this option to a different directory.

This option is also useful if Apache is not allowed to write to the system's temporary directory (which is the case on some systems with strict SELinux policies) or if the partition that the temporary directory lives on doesn't have enough disk space.

The instance directory is automatically removed when Apache shuts down.

Default value

The default value for this option is as follows:

• If you are on Red Hat, CentOS, Rocky, or Alma Linux and installed Passenger through the RPMs provided by Phusion, then the default value is /var/run/passenger-instreg.
• Otherwise, the default value is the value of the $TMPDIR environment variable. Or, if $TMPDIR is not set, /tmp.

Note regarding command line tools

Some Passenger command line administration tools, such as passenger-status, must know what Passenger's instance registry directory is in order to function properly. You can pass the directory through the PASSENGER_INSTANCE_REGISTRY_DIR or the TMPDIR environment variable.

For example, if you set 'PassengerInstanceRegistryDir' to '/my_temp_dir', then invoke passenger-status after you've set the PASSENGER_INSTANCE_REGISTRY_DIR, like this:

export PASSENGER_INSTANCE_REGISTRY_DIR=/my_temp-dir
sudo -E passenger-status

Notes regarding the above example:

• The -E option tells 'sudo' to preserve environment variables.
• If Passenger is installed through an RVM Ruby, then you must use rvmsudo instead of sudo.

PassengerFlyWith

Enables the Flying Passenger mode, and configures Apache to connect to the Flying Passenger daemon that's listening on the given socket filename.

Performance tuning

PassengerMaxPoolSize

The maximum number of application processes that may simultaneously exist. Generally speaking, the more application processes you run, the more concurrent traffic you can handle and the better your CPU core utilization becomes, until your hardware is saturated. But running more processes also means higher memory consumption.

The optimal value depends on your system's hardware and your workload. Please read the optimization guide to learn how to find out the optimal value.

This option behaves like a "safety switch" that prevents Passenger from overloading your system with too many processes. No matter how you configure PassengerMinInstances and PassengerMaxInstances, the total number of processes won't ever surpass the value set for this option. For example, if PassengerMaxPoolSize is set to 6, and you also deployed two applications on Passenger with each application's PassengerMinInstances set to 4, then the maximum number processes that may simultaneously exist is 6, not 8.

If you find that your server is running out of memory then you should lower this value. In order to prevent your server from crashing due to out-of-memory conditions, the default value is relatively low (6).

PassengerMinInstances

This specifies the minimum number of application processes that should exist for a given application. You should set this option to a non-zero value if you want to avoid potentially long startup times after a website has been idle for an extended period of time.

Please note that this option does not pre-start application processes during Apache startup. It just makes sure that when the application is first accessed:

1. at least the given number of processes will be spawned.
2. the given number of processes will be kept around even when processes are being idle cleaned.

If you want to pre-start application processes during Apache startup, then you should use the PassengerPreStart option, possibly in combination with PassengerMinInstances. This behavior might seem counter-intuitive at first sight, but PassengerPreStart explains the rationale behind it.

Example

Suppose that you have the following configuration:

PassengerMaxPoolSize 15
PassengerPoolIdleTime 10

<VirtualHost *:80>
  ServerName foobar.com
  DocumentRoot /webapps/foobar/public
  PassengerMinInstances 3
</VirtualHost>

When you start Apache, there are 0 application processes for 'foobar.com'. Things will stay that way until someone visits 'foobar.com'. Suppose that there is only one visitor. One application process will be started immediately to serve the visitor, while two will be spawned in the background. After 10 seconds, when the idle timeout has been reached, these 3 application processes will not be cleaned up.

Now suppose that there's a sudden spike of traffic, and 100 users visit 'foobar.com' simultaneously. Passenger will start 12 more application processes (15 - 3 = 12). After the idle timeout of 10 seconds has passed, Passenger will clean up 12 application processes, keeping 3 processes around.

PassengerMaxInstances

The maximum number of application processes that may simultaneously exist for an application. This helps to make sure that a single application will not occupy all available slots in the application pool.

This value must be less than PassengerMaxPoolSize. A value of 0 means that there is no limit placed on the number of processes a single application may spawn, i.e. only the global limit of PassengerMaxPoolSize will be enforced.

Example

Suppose that you're hosting two web applications on your server, a personal blog and an e-commerce website. You've set PassengerMaxPoolSize to 10. The e-commerce website is more important to you. You can then set PassengerMaxInstances to 3 for your blog, so that it will never spawn more than 3 processes, even if it suddenly gets a lot of traffic. Your e-commerce website on the other hand will be free to spawn up to 10 processes if it gets a lot of traffic.

PassengerMaxInstancesPerApp

The maximum number of application processes that may simultaneously exist for a single application. This helps to make sure that a single application will not occupy all available slots in the application pool.

This value must be less than PassengerMaxPoolSize. A value of 0 means that there is no limit placed on the number of processes a single application may use, i.e. only the global limit of PassengerMaxPoolSize will be enforced.

Example

Suppose that you're hosting two blogs (blog A and B) on your server, and that you've set PassengerMaxPoolSize to 10. Under normal circumstances, if blog A suddenly gets a lot of traffic, then A will use all 10 pool slots. If blog B suddenly gets some traffic, then it will only be able to use 1 pool slot (forcefully releasing 1 slot from A) until A's traffic has settled down and it has released more pool slots.

If you consider both blogs equally important, then you can set PassengerMaxInstancesPerApp to 5. This way, both blogs will never use more than 5 pool slots.

Relation to PassengerMaxInstances

Unlike PassengerMaxInstances, this configuration option is global and applies to all applications. PassengerMaxInstances on the other hand is per-virtual host.

Suppose that you're hosting two web applications on your server, a personal blog and an e-commerce website. You've set PassengerMaxPoolSize to 10. The e-commerce website is more important to you. You can then set PassengerMaxInstances to 3 for your blog, so that it will never use more than 3 pool slots, even if it suddenly gets a lot of traffic. Your e-commerce website on the other hand will be free to use up all 10 slots if it gets a lot of traffic.

In summary, PassengerMaxInstancesPerApp divides the pool equally among the different web applications, while 'PassengerMaxInstances' allows one to divide the pool unequally, according to each web application's relative importance.

PassengerPoolIdleTime

The maximum number of seconds that an application process may be idle. That is, if an application process hasn't received any traffic after the given number of seconds, then it will be shutdown in order to conserve memory.

Decreasing this value means that 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 web app. However, it will also free up resources used by applications more quickly.

The optimal value depends on the average time that a visitor spends on a single dynamic page. We recommend a value of 2 * x, where x is the average number of seconds that a visitor spends on a single dynamic page. But your mileage may vary.

When this value is set to 0, application processes will not be shutdown unless it's really necessary. Here is a situation where Passenger seems necessary to shutdown an application process. Suppose that you have two apps on your server, foo and bar. If a user visits foo, but there are no processes for foo, and at the same time there are lots of application processes for bar (as many as the pool limit), then Passenger will wait until one of those bar processes is no longer handling a request. At this time, that process will be shutdown so that Passenger can spawn a foo process.

Setting the value to 0 is recommended if you're on a non-shared host that's only running a few applications, each which must be available at all times.

PassengerMaxPreloaderIdleTime

The preloader process (explained in Spawn methods) has an idle timeout, just like the application processes spawned by Passenger do. That is, it will automatically shutdown a preloader process if it hasn't done anything for a given period.

This option allows you to set the preloader's idle timeout, in seconds. A value of 0 means that it should never idle timeout.

Setting a higher value will mean that the preloader is kept around longer, which may slightly increase memory usage. But as long as the preloader server is running, the time to spawn a Ruby application process only takes about 10% of the time that is normally needed, assuming that you're using the smart spawn method. So if your system has enough memory, then is it recommended that you set this option to a high value or to 0.

PassengerForceMaxConcurrentRequestsPerProcess

Use this option to tell Passenger how many concurrent requests the application can handle per process. A value of 0 means that each process can handle an unlimited number of connections, while a value of -1 (the default) means that Passenger will infer the value based on internal heuristics.

There are three main use cases for this option:

1. To make dynamic process scaling work in Node.js and Meteor applications. Set this option to approximately the number of concurrent requests at which the performance of a single process begins to degrade.
2. To make SSE and WebSockets work well in Ruby applications. Set this option to 0.
3. To specify the available concurrency of an app using the GLS capabilities of Passenger.

This option is a hint to Passenger and does not make the application actually able to handle that many concurrent requests per process. For example in Ruby applications, the amount of concurrency that your application process can handle usually depends on the number of configured threads. If you set the number of threads, then Passenger will automatically infer that Ruby applications' max concurrency per process equals the number of threads. But in non-standard cases where this heuristic fails (e.g. in situations where a WebSocket library such as Faye spawns threads to handle WebSockets) then you can use this option to override Passenger's heuristic.

It is recommended that you do not touch this configuration option unless you want to tweak Passenger for one of the three main use cases documented above.

PassengerConcurrencyModel

Specifies the I/O concurrency model that should be used for Ruby application processes. Passenger supports two concurrency models:

• process – single-threaded, multi-processed I/O concurrency. Each application process only has a single thread and can only handle 1 request at a time. This is the concurrency model that Ruby applications traditionally used. It has excellent compatibility (can work with applications that are not designed to be thread-safe) but is unsuitable for workloads in which the application has to wait for a lot of external I/O (e.g. HTTP API calls), and uses more memory because each process has a large memory overhead.
• thread – multi-threaded, multi-processed I/O concurrency. Each application process has multiple threads (customizable via PassengerThreadCount. This model provides much better I/O concurrency and uses less memory because threads share memory with each other within the same process. However, using this model may cause compatibility problems if the application is not designed to be thread-safe.

PassengerThreadCount

Specifies the number of threads that Passenger should spawn per Ruby application process. This option only has effect if PassengerConcurrencyModel is thread.

PassengerStatThrottleRate

By default, Passenger performs several filesystem checks (or, in programmers jargon, "stat() calls") each time a request is processed:

• It checks which the application startup files are present, in order to autodetect the application type.
• It checks whether restart.txt has changed or whether always_restart.txt exists, in order to determine whether the application should be restarted.

On some systems where disk I/O is expensive, e.g. systems where the harddisk is already being heavily loaded, or systems where applications are stored on NFS shares, these filesystem checks can incur a lot of overhead.

You can decrease or almost entirely eliminate this overhead by setting PassengerStatThrottleRate. Setting this option to a value of x means that the above list of filesystem checks will be performed at most once every x seconds. Setting it to a value of '0' means that no throttling will take place, or in other words, that the above list of filesystem checks will be performed on every request.

PassengerPreStart

By default, Passenger does not start any application processes until said web application is first accessed. The result is that the first visitor of said web application might experience a small delay as Passenger is starting the web application on demand. If that is undesirable, then this option can be used to pre-started application processes during Apache startup.

A few things to be careful of:

• This option accepts the URL of the web application you want to pre-start, not a on/off value! This might seem a bit weird, but read on for rationale. As for the specifics of the URL:
• The domain part of the URL must be equal to the value of the ServerName option of the VirtualHost block that defines the web application.
• Unless the web application is deployed on port 80, the URL should contain the web application's port number too.
• The path part of the URL must point to some URI that the web application handles.
• You will probably want to combine this option with PassengerMinInstances because application processes started with PassengerPreStart are subject to the usual idle timeout rules. See the example below for an explanation.

Example 1: basic usage

Suppose that you have the following web applications.

<VirtualHost *:80>
  ServerName foo.com
  DocumentRoot /webapps/foo/public
</VirtualHost>

<VirtualHost *:3500>
  ServerName bar.com
  DocumentRoot /webapps/bar/public
</VirtualHost>

You want both of them to be pre-started during Apache startup. The URL for foo.com is http://foo.com/ (or, equivalently, http://foo.com:80/) and the URL for bar.com is http://bar.com:3500/. So we add two PassengerPreStart options, like this:

<VirtualHost *:80>
  ServerName foo.com
  DocumentRoot /webapps/foo/public
</VirtualHost>

<VirtualHost *:3500>
  ServerName bar.com
  DocumentRoot /webapps/bar/public
</VirtualHost>

PassengerPreStart http://foo.com/           # <--- added
PassengerPreStart http://bar.com:3500/      # <--- added

Example 2: pre-starting apps that are deployed in sub-URIs

Suppose that you have a web application deployed in a sub-URI /store, like this:

<VirtualHost *:80>
  ServerName myblog.com
  DocumentRoot /webapps/wordpress

  Alias /store /websites/store/public
  <Location /store>
    PassengerBaseURI /store
    PassengerAppRoot /websites/store
  </Location>
  <Directory /websites/store/public>
    Allow from all
    Options -MultiViews
    # Uncomment this if you're on Apache &ge; 2.4:
    #Require all granted
  </Directory>
</VirtualHost>

Then specify the domain name of its containing virtual host followed by the sub-URI, like this:

<VirtualHost *:80>
  ServerName myblog.com
  DocumentRoot /webapps/wordpress

  Alias /store /websites/store/public
  <Location /store>
    PassengerBaseURI /store
    PassengerAppRoot /websites/store
  </Location>
  <Directory /websites/store/public>
    Allow from all
    Options -MultiViews
    # Uncomment this if you're on Apache &ge; 2.4:
    #Require all granted
  </Directory>
</VirtualHost>

PassengerPreStart http://myblog.com/store    # <----- added

The sub-URI must be included; if you don't then the option will have no effect. The following example is wrong and won't pre-start the store web application:

PassengerPreStart http://myblog.com/    # <----- WRONG! Missing "/store" part.

Example 3: combining with PassengerMinInstances

Application processes started with PassengerPreStart are also subject to the idle timeout rules as specified by PassengerPoolIdleTime! That means that by default, the pre-started application processes for foo.com and bar.com are shut down after a few minutes of inactivity. If you don't want that to happen, then you should combine PassengerPreStart with PassengerMinInstances, like this:

<VirtualHost *:80>
  ServerName foo.com
  DocumentRoot /webapps/foo/public
  # Added!
  PassengerMinInstances 1
</VirtualHost>

<VirtualHost *:3500>
  ServerName bar.com
  DocumentRoot /webapps/bar/public
  # Added!
  PassengerMinInstances 1
</VirtualHost>

PassengerPreStart http://foo.com/
PassengerPreStart http://bar.com:3500/

So why a URL? Why not just an on/off flag?

An option that accepts a simple on/off flag is definitely more intuitive, but due technical difficulties w.r.t. the way Apache works, it's very hard to implement it like that:

• It is very hard to obtain a full list of web applications defined in the Apache configuration file(s). In other words, it's hard for Passenger to know which web applications are deployed on Apache until a web application is first accessed, and without such a list Passenger wouldn't know which web applications to pre-start. It's probably not completely impossible to obtain such a list, but this brings us to the following point;
• Users expect things like mod_env to work even in combination with Passenger. For example some people put SetEnv PATH .... in their virtual host block and they expect the web application to pick that environment variable up when it's started. Information like this is stored in module-specific locations that Passenger cannot access directly. Even if the previous bullet point is solved and we can obtain a list of web applications, we cannot start the application with the correct mod_env information. mod_env is just one such example; there are probably many other Apache modules, all of which people expect to work, but we cannot answer to those expectations if PassengerPreStart is implemented as a simple on/off flag.

So as a compromise, we made it accept a URL. This is easier to implement for us and altough it looks weird, it behaves consistently w.r.t. cooperation with other Apache modules.

What does Passenger do with the URL?

During Apache startup, Passenger will send a dummy HEAD request to the given URL and discard the result. In other words, Passenger simulates a web access at the given URL. However this simulated request is always sent to localhost, not to the IP that the domain resolves to. Suppose that bar.com in example 1 resolves to 209.85.227.99; Passenger will send the following HTTP request to 127.0.0.1 port 3500 (and not to 209.85.227.99 port 3500):

HEAD / HTTP/1.1
Host: bar.com
Connection: close

Similarly, for example 2, Passenger will send the following HTTP request to 127.0.0.1 port 80:

HEAD /store HTTP/1.1
Host: myblog.com
Connection: close

Do I need to edit /etc/hosts and point the domain in the URL to 127.0.0.1?

No. See previous subsection.

My web application consists of multiple web servers. What URL do I need to specify, and in which web server's Apache config file?

Put the web application's virtual host's ServerName value and the virtual host's port in the URL, and put PassengerPreStart on all machines that you want to pre-start the web application on. The simulated web request is always sent to 127.0.0.1, with the domain name in the URL as value for the Host HTTP header, so you don't need to worry about the request ending up at a different web server in the cluster.

Does PassengerPreStart support https:// URLs?

Yes. And it does not perform any certificate validation.

PassengerHighPerformance

By default, Passenger is compatible with mod_rewrite and most other Apache modules. However, a lot of effort is required in order to be compatible. If you turn PassengerHighPerformance on, then Passenger will be a little faster, in return for reduced compatibility with other Apache modules.

In places where PassengerHighPerformance is turned on, mod_rewrite rules will likely not work. mod_autoindex (the module which displays a directory index) will also not work. Other Apache modules may or may not work, depending on what they exactly do. We recommend you to find out how other modules behave in high performance mode via testing.

This option is not an all-or-nothing global option: you can enable high performance mode for certain virtual hosts or certain URLs only.

When to enable high performance mode?

If you do not use mod_rewrite or other Apache modules then it might make sense to enable high performance mode.

It's likely that some of your applications depend on mod_rewrite or other Apache modules, while some do not. In that case you can enable high performance for only those applications that don't use other Apache modules. For example:

<VirtualHost *:80>
  ServerName www.foo.com
  DocumentRoot /apps/foo/public
  .... mod_rewrite rules or options for other Apache modules here ...
</VirtualHost>

<VirtualHost *:80>
  ServerName www.bar.com
  DocumentRoot /apps/bar/public
  PassengerHighPerformance on
</VirtualHost>

In the above example, high performance mode is only enabled for www.bar.com. It is disabled for everything else.

If your application generally depends on mod_rewrite or other Apache modules, but a certain URL that's accessed often doesn't depend on those other modules, then you can enable high performance mode for a certain URL only. For example:

<VirtualHost *:80>
  ServerName www.foo.com
  DocumentRoot /apps/foo/public
  .... mod_rewrite rules or options for other Apache modules here ...

  <Location /chatroom/ajax_update_poll>
    PassengerHighPerformance on
  </Location>
</VirtualHost>

This enables high performance mode for http://www.foo.com/chatroom/ajax_update_poll only.

PassengerResponseBufferHighWatermark

As explained in PassengerBufferResponse, Passenger has two response buffering mechanisms. This option configures the maximum size of the real-time disk-backed response buffering system. If the buffer is full, the application will be blocked until the client has fully read the buffer.

This buffering system has a default size of 128 MB (134217728 bytes). This default value is large enough to prevent most applications from blocking on slow clients, but small enough to prevent broken applications from filling up the hard disk.

You can't disable real-time disk-backed response buffering, but you can set the buffer size to a small value, which is effectively the same as disabling it.

Most of the time, you won't need to tweak this value. But there is one good use case where you may want set this option to a low value: if you are streaming a large response, but want to detect client disconnections as soon as possible. If the buffer size is larger than your response size, then Phusion Passenger will read and buffer the response as fast as it can, offloading the application as soon as it can, thereby preventing the application from detecting client disconnects. But if the buffer size is sufficiently small (say, 64 KB), then your application will effectively output response data at the same speed as the client reads it, allowing you to detect client disconnects almost immediately. This is also a down side, because many slow clients blocking your application can result in a denial of service, so use this option with care.

If your application outputs responses larger than 128 MB and you are not interested in detecting client disconnects as soon as possible, then you should raise this value, or set it to 0.

A value of 0 means that the buffer size is unlimited.

PassengerMaxRequestQueueSize

When all application processes are already handling their maximum number of concurrent requests, Passenger will queue all incoming requests. This option specifies the maximum size for that queue. If the queue is already at this specified limit, then Passenger will immediately send a "503 Service Unavailable" error to any incoming requests.

A value of 0 means that the queue is unbounded.

This article on StackOverflow explains how the request queue works, what it means for the queue to grow or become full, why that is bad, and what you can do about it.

You may combine this option with PassengerErrorOverride and ErrorDocument to set a custom error page whenever the queue is full. In the following example, Apache will serve /error503.html whenever the queue is full:

PassengerErrorOverride on
ErrorDocument 503 /error503.html

PassengerMaxRequestQueueTime

When all application processes are already handling their maximum number of concurrent requests, Passenger will queue all incoming requests. This option specifies the maximum time a request may spend in that queue. If a request in the queue reaches this specified limit, then Passenger will send a "504 Gateway Timeout" error for that request. For performance reasons it might take up to 0.5 × PassengerMaxRequestQueueTime after a request timed out before a 504 response is sent (when all application processes are stuck).

A value of 0 means that the queue time is unbounded.

This blog article explains how to use this option to optimize the user experience during rush hour, when queueing starts happening.

You may combine this option with PassengerErrorOverride and ErrorDocument to set a custom error page whenever a request in the queue times out. In the following example, Apache will serve /error504.html whenever the queue is full:

PassengerErrorOverride on
ErrorDocument 504 /error504.html

PassengerSocketBacklog

The socket backlog is a queue of incoming connections (from Apache) not yet acknowledged by Passenger. This option can be raised if Apache manages to overflow the backlog queue, for example because Passenger is receiving insufficient server resources to accept connections into its internal queue.

PassengerTurbocaching

When set of off, will disable Passenger's turbocache.

Security

PassengerUserSwitching

Whether to attempt to enable user account sandboxing, also known as user switching.

PassengerUser

If user account sandboxing (also known as user switching) is enabled, then Passenger will by default run the web application as the owner of the application's startup file. PassengerUser allows you to override that behavior and explicitly set a user to run the web application as, regardless of the ownership of the startup file.

PassengerGroup

If user account sandboxing (also known as user switching) is enabled, then Passenger will by default run the web application as the primary group of the owner of the application's startup file. PassengerGroup allows you to override that behavior and explicitly set a group to run the web application as, regardless of the ownership of the startup file.

The value may also be set to the special value !STARTUP_FILE!, in which case the web application's group will be set to the startup file's group.

PassengerDefaultUser

Passenger enables user account sandboxing (also known as user switching) by default. This configuration option allows you to specify the user that applications must run as, if user switching fails or is disabled.

PassengerDefaultGroup

Passenger enables user account sandboxing (also known as user switching) by default. This configuration option allows you to specify the group that applications must run as, if user switching fails or is disabled.

The default value is the primary group of the user specifified by PassengerDefaultUser. So the default value on most systems is nobody or nogroup.

PassengerShowVersionInHeader

When turned on, Passenger will output its version number in the X-Powered-By header in all Passenger-served requests:

X-Powered-By: Phusion Passenger 5.0.13

When turned off, the version number will be hidden:

X-Powered-By: Phusion Passenger

PassengerFriendlyErrorPages

Passenger can display friendly error pages whenever an application fails to start. This friendly error page presents the startup error message, some suggestions for solving the problem, a backtrace and a dump of the environment variables.

This feature is very useful during application development and useful for less experienced system administrators, but the page might reveal potentially sensitive information, depending on the application. For this reason, friendly error pages are disabled by default, unless PassengerAppEnv (or its aliases such as RailsEnv and RackEnv) is set to development. You can use this option to explicitly enable or disable this feature.

PassengerDisableSecurityUpdateCheck

This option allows disabling the Passenger security update check, a daily check with https://securitycheck.phusionpassenger.com for important security updates that might be available.

PassengerSecurityUpdateCheckProxy

This option allows use of an intermediate proxy for the Passenger security update check. The proxy client code uses libcurl, which supports the following values for scheme:
http, socks5, socks5h, socks4, socks4a

PassengerDisableAnonymousTelemetry

This option allows disabling the Passenger anonymous telemetry reporting, which regularly sends anonymous telemetry data to https://anontelemetry.phusionpassenger.com.

PassengerAnonymousTelemetryProxy

This option allows use of an intermediate proxy for the Passenger anonymous telemetry reporting. The proxy client code uses libcurl, which supports the following values for scheme:
http, socks5, socks5h, socks4, socks4a

PassengerDataBufferDir

By default, Passenger buffers the following things to disk:

• Large HTTP client request bodies. This prevents slow HTTP clients from blocking web applications by sending request bodies very slowly. Read PassengerBufferUpload to learn more.
• Large web application responses. This prevents slow HTTP clients from blocking web applications by reading responses very slowly. This feature is also known as "real-time disk-backed response buffering".

By default, such buffers are stored in the directory given by the $TMPDIR environment variable, or (if $TMPDIR is not set) the /tmp directory. This configuration directive allows you to specify a different directory.

Changing this option is especially useful in the following cases:

• If Apache is not allowed to write to the system's temporary directory. This is the case on some systems with strict SELinux policies.
• If the partition that the default directory lives on doesn't have enough disk space.

If you've specified such a directory (as opposed to using Passenger's default) then you must ensure that this directory exists.

You can disable client request body buffering by turning PassengerBufferUpload off. It is not possible to turn off real-time disk-backed response buffering.

This option may be specified once, in the global server configuration.

PassengerBufferUpload

When turned on, HTTP client request bodies will be buffered before they are sent to the application. This buffering protects the application from slow clients, but also prevents the ability to track upload progress.

If you want to allow your application to track upload progress, it is recommended that you disable upload buffering for specific URIs only. For example:

# Disable upload buffering for /upload_video only.
<Location /upload_video>
  PassengerBufferUpload off
</Location>

PassengerBufferResponse

When turned on, application-generated responses are buffered by Apache. Buffering will happen in memory.

Before we proceed with explaining this configuration option, we want to state the following to avoid confusion. If you use Passenger for Apache, there are in fact two response buffering systems active:

1. The Apache response buffering system. PassengerBufferResponse turns this on or off.
2. The Passenger response buffering system, a.k.a. "real-time disk-backed response buffering". This buffering system is always on, regardless of the value of PassengerBufferResponse, but its behavior can be tweaked with PassengerResponseBufferHighWatermark.

Response buffering is useful because it protects against slow HTTP clients that do not read responses immediately or quickly enough. Buffering prevents such slow clients from blocking web applications that have limited concurrency. Because Passenger's response buffering is always turned on, you are always protected. Therefore, PassengerBufferResponse is off by default, and you never should have to turn it on.

If for whatever reason you want to turn Apache-level response buffering on, you can do so with this option.

Apache's response buffering works differently from Passenger's. Apache's buffering system buffers the entire response before attempting to send it to the client, while Passenger's attempts to send the data to the client immediately. Therefore, if you turn on PassengerBufferResponse, you may interfere with applications that want to stream responses to the client. Apache's version also buffers to memory only, making it problematic for large responses. Passenger's version buffers to disk when the response exceeds a certain threshold.

So keep in mind that enabling PassengerBufferResponse will make streaming responses impossible. Consider for example this piece of Ruby on Rails code:

render :text => lambda { |response, output|
10.times do |i|
output.write("entry #{i}\n")
output.flush
sleep 1
end
}

…or this piece of Ruby Rack code:

class Response
def each
10.times do |i|
yield("entry #{i}\n")
sleep 1
end
end
end

app = lambda do |env|
[200, { "Content-Type" => "text/plain" }, Response.new]
end

When PassengerBufferResponse is turned on, Apache will wait until the application is done sending the entire response before forwarding it to the client. The client will not receive anything for 10 seconds, after which it receives the entire response at once. When PassengerBufferResponse is turned off, it works as expected: the client receives an "entry X" message every second for 10 seconds.

PassengerAllowEncodedSlashes

By default, Apache doesn't support URLs with encoded slashes (%2f), e.g. URLs like this: /users/fujikura%2fyuu. If you access such an URL then Apache will return a 404 Not Found error. This can be solved by turning on PassengerAllowEncodedSlashes as well as Apache's AllowEncodedSlashes.

Is it important that you turn on both AllowEncodedSlashes and PassengerAllowEncodedSlashes, otherwise this feature will not work properly.

Please note however that turning on support for encoded slashes will break support for mod_rewrite passthrough rules. Because of bugs/limitations in Apache, Passenger can support either encoded slashes or mod_rewrite passthrough rules, but not both at the same time. Luckily this option can be specified anywhere, so you can enable it only for virtual hosts or URLs that need it:

<VirtualHost *:80>
    ServerName www.example.com
    DocumentRoot /webapps/example/public
    AllowEncodedSlashes on
    RewriteEngine on

    # Check for maintenance file and redirect all requests
    RewriteCond %{DOCUMENT_ROOT}/system/maintenance.html -f
    RewriteCond %{SCRIPT_FILENAME} !maintenance.html
    RewriteRule ^.*$ /system/maintenance.html [L]

    # Make /about an alias for /info/about.
    RewriteRule ^/about$ /info/about [PT,L]

    <Location ~ "^/users/">
    # In a location block so that it doesn't interfere with the
      # above /about mod_rewrite rule.
        PassengerAllowEncodedSlashes on
    </Location>
</VirtualHost>

With this, http://www.example.com/users/fujikura%2fyuu will work properly, and accessing http://www.example.com/about will properly display the result of http://www.example.com/info/about. Notice that PassengerAllowEncodedSlashes only interferes with passthrough rules, not with any other mod_rewrite rules. The rules for displaying maintenance.html will work fine even for URLs starting with "/users".

PassengerLveMinUid

When using Passenger on a LVE-enabled kernel, a security check (enter) is run for spawning application processes. This options tells the check to only allow processes with UIDs equal to, or higher than, the specified value.

PassengerSpawnDir

The directory in which Passenger will record progress during startup, which is specifically useful for users using sandbox tech such as CageFS, SElinux, or macOS sandboxes. The default value is the value of the $TMPDIR environment variable. Or, if $TMPDIR is not set, /tmp.

PassengerDirectInstanceRequestAddress

The port which Passenger will cause your ruby app to additionally bind to, to allow sending requests directly to specific app instances. Sending requests to specific app processes is detailed here.

Request / response customization

PassengerBaseURI

Used to specify that the given URI is an distinct application that should be served by Passenger. Please see the deployment guide for more information.

PassengerCustomErrorPage

Replaces the default Passenger error page when there is an issue spawning an app.

By default, Passenger either renders a friendly error page or a minimal error page depending on the PassengerFriendlyErrorPages and PassengerAppEnv config options. This option overrides the error page with your own. The path should point to a static file which Passenger has permission to read.

PassengerErrorOverride

Decides whether Apache will intercept and handle responses with HTTP status codes of 400 and higher. This option is useful where you want to have a common look and feel on the error pages seen by the end user. This also allows for included files (via mod_include's SSI) to get the error code and act accordingly (default behavior would display the error page of the proxied server, turning this on shows the SSI Error message).

This option does not affect the processing of informational (1xx), normal success (2xx), or redirect (3xx) responses.

By default, all responses are sent as-is from the application or from the Passenger core. If you turn this option on then Apache will be able to handle such responses using the Apache ErrorDocument option.

PassengerStickySessions

When sticky sessions are enabled, all requests that a client sends will be routed to the same originating application process, whenever possible. When sticky sessions are disabled, requests may be distributed over multiple processes, and may not necessarily be routed to the originating process, in order to balance traffic over multiple CPU cores. Because of this, sticky sessions should only be enabled in specific circumstances.

For applications that store important state inside the process's own memory – that is, as opposed to storing state in a distributed data store, such as the database or Redis – sticky sessions should be enabled. This is because otherwise, some requests could be routed to a different process, which stores different state data. Because processes don't share memory with each other, there's no way for one process to know about the state in another process, and then things can go wrong.

One prominent example is the popular SockJS library, which is capable of emulating WebSockets through long polling. This is implemented through two HTTP endpoints, /SESSION_ID/xhr_stream (a long polling end point which sends data from the server to the client), and /SESSION_ID/xhr_send (a normal POST endpoint which is used for sending data from the client to the server). SockJS correlates the two requests with each other through a session identifier. At the same time, in its default configuration, it stores all known session identifiers in an in-memory data structure. It is therefore important that a particular /SESSION_ID/xhr_send request is sent to the same process where the corresponding /SESSION_ID/xhr_stream request originates from; otherwise, SockJS cannot correlate the two requests, and an error occurs.

So prominent examples where sticky sessions should (or even must) be enabled, include:

• Applications that use the SockJS library (unless configured with a distributed data store)
• Applications that use the Socket.io library (unless configured with a distributed data store)
• Applications that use the faye-websocket gem (unless configured with a distributed data store)
• Meteor JS applications (because Meteor uses SockJS)

Sticky sessions work through the use of a special cookie, whose name can be customized with PassengerStickySessionsCookieName. Passenger puts an identifier in this cookie, which tells Passenger what the originating process is. Next time the client sends a request, Passenger reads this cookie and uses the value in the cookie to route the request back to the originating process. If the originating process no longer exists (e.g. because it has crashed or restarted) then Passenger will route the request to some other process, and reset the cookie.

If you have a load balancer in front end of Passenger + Apache, then you must configure sticky sessions on that load balancer too. Otherwise, the load balancer could route the request to a different server.

PassengerStickySessionsCookieName

Sets the name of the sticky sessions cookie.

PassengerStickySessionsCookieAttributes

Sets the attributes of the sticky sessions cookie.

Logging & troubleshooting

PassengerLogLevel

This option allows one to specify how much information Passenger should log to its log file. A higher log level value means that more information will be logged.

Possible values are:

• 0 (crit): Show only critical errors which would cause Passenger to abort.
• 1 (error): Also show non-critical errors – errors that do not cause Passenger to abort.
• 2 (warn): Also show warnings. These are not errors, and Passenger continues to operate correctly, but they might be an indication that something is wrong with the system.
• 3 (notice): Also show important informational messages. These give you a high-level overview of what Passenger is doing.
• 4 (info): Also show less important informational messages. These messages show more details about what Passenger is doing. They're high-level enough to be readable by users.
• 5 (debug): Also show the most important debugging information. Reading this information requires some system or programming knowledge, but the information shown is typically high-level enough to be understood by experienced system administrators.
• 6 (debug2): Show more debugging information. This is typically only useful for developers.
• 7 (debug3): Show even more debugging information.

PassengerDisableLogPrefix

PassengerLogFile

By default Passenger log messages are written to the Apache global error log. With this option, you can have those messages logged to a different file instead.

PassengerAppLogFile

By default Passenger log messages are all written to the Passenger log file. With this option, you can have the app specific messages logged to a different file in addition.

PassengerFileDescriptorLogFile

Log file descriptor debug tracing messages to the given file.

Passenger has the ability to log all file descriptors that it opens and closes. These logs are useful to the Passenger developers for the purpose of analyzing file descriptor leaks.

File descriptor activity is logged as follows:

• If PassengerFileDescriptorLogFile is not set, then file descriptor activity is logged to the main log file, but only if the log level is 5 (debug) or higher.
• If PassengerFileDescriptorLogFile is set, then file descriptor activity is logged to the specified file, regardless of the log level.

PassengerDebugger

Turns support for Ruby application debugging on or off. Please read the Ruby debugging console guide for more information.

PassengerAdminPanelUrl

The URI to connect to the Fuse Panel with. Information is sent to enable monitoring, administering, analysis and troubleshooting of this Passenger instance and apps running on it. The feature is disabled if this option is not specified. See "Connect Passengers" in the Fuse Panel for further instructions.

PassengerAdminPanelAuthType

The authentication method Passenger should use when connecting to the Fuse Panel. Currently only basic authentication is supported. See "Connect Passengers" in the Fuse Panel for further instructions.

PassengerAdminPanelUsername

The username that Passenger should use when connecting to the Fuse Panel with basic authentication. See "Connect Passengers" in the Fuse Panel for further instructions.

PassengerAdminPanelPassword

The password that Passenger should use when connecting to the Fuse Panel with basic authentication. See "Connect Passengers" in the Fuse Panel for further instructions.

PassengerDumpConfigManifest

If specified, Passenger will dump a representation of its own configuration to the given file, in JSON format. This option is usually only interesting to Passenger developers for the purpose of developing configuration-related features.

PassengerMaxRequests

The maximum number of requests an application process will process. After serving that many requests, the application process will be shut down and Passenger will restart it. A value of 0 means that there is no maximum. The application process might also be shut down if its idle timeout is reached.

This option is useful if your application is leaking memory. By shutting it down after a certain number of requests, all of its memory is guaranteed to be freed by the operating system. An alternative (and better) mechanism for dealing with memory leaks is PassengerMemoryLimit.

PassengerMaxRequestTime

The maximum amount of time, in seconds, that an application process may take to process a request. If the request takes longer than this amount of time, then the application process will be forcefully shut down, and possibly restarted upon the next request. A value of 0 means that there is no time limit.

This option is useful for preventing your application from getting stuck for an indefinite period of time.

Example

Suppose that most of your requests are known to finish within 2 seconds. However, there is one URI, /expensive_computation, which is known to take up to 10 seconds. You can then configure Passenger as follows:

<VirtualHost *:80>
  ServerName www.example.com
  DocumentRoot /webapps/my_app/public

  PassengerMaxRequestTime 2
  <Location /expensive_computation>
    PassengerMaxRequestTime 10
  </Location>
</VirtualHost>

If a request to '/expensive_computation' takes more than 10 seconds, or if a request to any other URI takes more than 2 seconds, then the corresponding application process will be forced to shutdown.

PassengerMemoryLimit

The soft limit on memory that an application process may use, in megabytes. Once an application process has surpassed this memory limit, Passenger allow it to finish processing all of its current requests, then shuts the process down. A value of 0 means that there is no maximum: the application's memory usage will not be checked.

This option is useful if your application is leaking memory. By shutting it down, all of its memory is guaranteed to be freed by the operating system.

PassengerHardMemoryLimit

The hard limit on memory that an application process may use, in megabytes. Once an application process has surpassed this memory limit, Passenger will kill it within PassengerAnalyticsCollectionRate seconds. A value of 0 means that there is no maximum: the application's memory usage will not result in Passenger killing the process (though the kernel oom killer may still kill the process).

This option is useful if your application is leaking memory. By shutting it down, all of its memory is guaranteed to be freed by the operating system.

PassengerAnalyticsCollectionRate

The time Passenger waits between checking the memory use of your application processes, in seconds. A longer duration will allow processes over the memory limit to live longer, but a lower duration will use more CPU time.

Deprecated or removed options

The following options have been deprecated or removed. Some are still supported for backwards compatibility reasons.

RailsRuby

Deprecated in 3.0.0 in favor of PassengerRuby.

RailsBaseURI, RackBaseURI

Deprecated in 3.0.0 in favor of PassengerBaseURI.

RailsUserSwitching

Deprecated in 3.0.0 in favor of PassengerUserSwitching.

RailsDefaultUser

Deprecated in 3.0.0 in favor of PassengerDefaultUser.

RailsAllowModRewrite

This option doesn't do anything anymore in since version 4.0.0.

RailsSpawnMethod

Deprecated in 3.0.0 in favor of PassengerSpawnMethod.

RailsAutoDetect, RackAutoDetect and WsgiAutoDetect

These options have been removed in version 4.0.0 as part of an optimization. You should use PassengerEnabled instead.

RailsAppSpawnerIdleTime

This option has been removed in version 4.0.0, and replaced with PassengerMaxPreloaderIdleTime.

RailsFrameworkSpawnerIdleTime

This option is no longer available in version 4.0.0. There is no alternative because framework spawning has been removed altogether. You should use smart spawning instead.

PassengerDebugLogFile

This option has been renamed in version 5.0.5 to PassengerLogFile.

PassengerResolveSymlinksInDocumentRoot

This option is no longer available in version 5.2.0. Switch to PassengerAppRoot if you are setting the application root via a document root containing symlinks.