#include <SpawnManager.h>
This class is responsible for spawning new instances of Ruby on Rails applications. Use the spawn() method to do so.
Internally, this class makes use of a spawn server, which is written in Ruby. This server is automatically started when a SpawnManager instance is created, and automatically shutdown when that instance is destroyed. The existance of the spawn server is almost totally transparent to users of this class. Spawn requests are sent to the server, and details about the spawned process is returned.
If the spawn server dies during the middle of an operation, it will be restarted. See spawn() for full details.
The communication channel with the server is anonymous, i.e. no other processes can access the communication channel, so communication is guaranteed to be safe (unless, of course, if the spawn server itself is a trojan).
The server will try to keep the spawning time as small as possible, by keeping corresponding Ruby on Rails frameworks and application code in memory. So the second time an instance of the same application is spawned, the spawn time is significantly lower than the first time. Nevertheless, spawning is a relatively expensive operation (compared to the processing of a typical HTTP request/response), and so should be avoided whenever possible.
See the documentation of the spawn server for full implementation details.
Public Member Functions | |
| SpawnManager (const string &spawnServerCommand, const string &logFile="", const string &environment="production", const string &rubyCommand="ruby", const string &user="") | |
| Construct a new SpawnManager. | |
| ApplicationPtr | spawn (const string &appRoot, bool lowerPrivilege=true, const string &lowestUser="nobody") |
| Spawn a new instance of a Ruby on Rails application. | |
| void | reload (const string &appRoot) |
| Remove the cached application instances at the given application root. | |
| pid_t | getServerPid () const |
| Get the Process ID of the spawn server. | |
| Passenger::SpawnManager::SpawnManager | ( | const string & | spawnServerCommand, | |
| const string & | logFile = "", |
|||
| const string & | environment = "production", |
|||
| const string & | rubyCommand = "ruby", |
|||
| const string & | user = "" | |||
| ) | [inline] |
Construct a new SpawnManager.
| spawnServerCommand | The filename of the spawn server to use. | |
| logFile | Specify a log file that the spawn server should use. Messages on its standard output and standard error channels will be written to this log file. If an empty string is specified, no log file will be used, and the spawn server will use the same standard output/error channels as the current process. | |
| environment | The RAILS_ENV environment that all RoR applications should use. If an empty string is specified, the current value of the RAILS_ENV environment variable will be used. | |
| rubyCommand | The Ruby interpreter's command. | |
| user | The user that the spawn manager should run as. This parameter only has effect if the current process is running as root. If the empty string is given, or if the user is not a valid username, then the spawn manager will be run as the current user. |
| SystemException | An error occured while trying to setup the spawn server. | |
| IOException | The specified log file could not be opened. |
| ApplicationPtr Passenger::SpawnManager::spawn | ( | const string & | appRoot, | |
| bool | lowerPrivilege = true, |
|||
| const string & | lowestUser = "nobody" | |||
| ) | [inline] |
Spawn a new instance of a Ruby on Rails application.
If the spawn server died during the spawning process, then the server will be automatically restarted, and another spawn attempt will be made. If restarting the server fails, or if the second spawn attempt fails, then an exception will be thrown.
If lowerPrivilege is true, then it will be attempt to switch the spawned application instance to the user who owns the application's config/environment.rb, and to the default group of that user.
If that user doesn't exist on the system, or if that user is root, then it will be attempted to switch to the username given by lowestUser (and to the default group of that user). If lowestUser doesn't exist either, or if switching user failed (because the spawn server process does not have the privilege to do so), then the application will be spawned anyway, without reporting an error.
It goes without saying that lowering privilege is only possible if the spawn server is running as root (and thus, by induction, that Passenger and Apache's control process are also running as root). Note that if Apache is listening on port 80, then its control process must be running as root. See "doc/Security of user switching.txt" for a detailed explanation.
| appRoot | The application root of a RoR application, i.e. the folder that contains 'app/', 'public/', 'config/', etc. This must be a valid directory, but the path does not have to be absolute. | |
| lowerPrivilege | Whether to lower the application's privileges. | |
| lowestUser | The user to fallback to if lowering privilege fails. |
| SpawnException | Something went wrong. |
| void Passenger::SpawnManager::reload | ( | const string & | appRoot | ) | [inline] |
Remove the cached application instances at the given application root.
Application code might be cached in memory. But once it a while, it will be necessary to reload the code for an application, such as after deploying a new version of the application. This method makes sure that any cached application code is removed, so that the next time an application instance is spawned, the application code will be freshly loaded into memory.
| SystemException | Unable to communicate with the spawn server, even after a restart. | |
| SpawnException | The spawn server died unexpectedly, and a restart was attempted, but it failed. |
| pid_t Passenger::SpawnManager::getServerPid | ( | ) | const [inline] |
Get the Process ID of the spawn server.
This method is used in the unit tests and should not be used directly.
1.5.3