passenger 4.0.2 → 4.0.3

data/ext/apache2/Configuration.hpp

@@ -25,10 +25,11 @@
 #ifndef _PASSENGER_CONFIGURATION_HPP_
 #define _PASSENGER_CONFIGURATION_HPP_
 
-#include "Utils.h"
-#include "Logging.h"
-#include "ServerInstanceDir.h"
-#include "Constants.h"
+#include <Logging.h>
+#include <ServerInstanceDir.h>
+#include <Constants.h>
+#include <Utils.h>
+#include <Utils/VariantMap.h>
 
 /* The APR headers must come after the Passenger headers. See Hooks.cpp
  * to learn why.
@@ -334,6 +335,8 @@ struct ServerConfig {
 	/** The Passenger root folder. */
 	const char *root;
 
+	VariantMap ctl;
+
 	/** The default Ruby interpreter to use. */
 	const char *defaultRuby;
 	

data/ext/apache2/Hooks.cpp

@@ -1,6 +1,6 @@
 /*
  *  Phusion Passenger - https://www.phusionpassenger.com/
- *  Copyright (c) 2010, 2011, 2012 Phusion
+ *  Copyright (c) 2010-2013 Phusion
  *
  *  "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.
  *
@@ -53,7 +53,7 @@
 #include "Utils/IOUtils.h"
 #include "Utils/Timer.h"
 #include "Logging.h"
-#include "AgentsStarter.hpp"
+#include "AgentsStarter.h"
 #include "DirectoryMapper.h"
 #include "Constants.h"
 
@@ -1237,7 +1237,7 @@ private:
 public:
 	Hooks(apr_pool_t *pconf, apr_pool_t *plog, apr_pool_t *ptemp, server_rec *s)
 	    : cstat(1024),
-	      agentsStarter(AgentsStarter::NGINX)
+	      agentsStarter(AS_APACHE)
 	{
 		serverConfig.finalize();
 		Passenger::setLogLevel(serverConfig.logLevel);
@@ -1258,23 +1258,33 @@ public:
 				"TIP: The correct value for this option was given to you by "
 				"'passenger-install-apache2-module'.");
 		}
+
+		VariantMap params;
+		params
+			.setPid ("web_server_pid", getpid())
+			.setUid ("web_server_worker_uid", unixd_config.user_id)
+			.setGid ("web_server_worker_gid", unixd_config.group_id)
+			.setInt ("log_level", serverConfig.logLevel)
+			.set    ("debug_log_file", (serverConfig.debugLogFile == NULL) ? "" : serverConfig.debugLogFile)
+			.set    ("temp_dir", serverConfig.tempDir)
+			.setBool("user_switching", serverConfig.userSwitching)
+			.set    ("default_user", serverConfig.defaultUser)
+			.set    ("default_group", serverConfig.defaultGroup)
+			.set    ("default_ruby", serverConfig.defaultRuby)
+			.setInt ("max_pool_size", serverConfig.maxPoolSize)
+			.setInt ("pool_idle_time", serverConfig.poolIdleTime)
+			.setInt ("max_instances_per_app", serverConfig.maxInstancesPerApp)
+			.set    ("analytics_log_user", serverConfig.analyticsLogUser)
+			.set    ("analytics_log_group", serverConfig.analyticsLogGroup)
+			.set    ("union_station_gateway_address", serverConfig.unionStationGatewayAddress)
+			.setInt ("union_station_gateway_port", serverConfig.unionStationGatewayPort)
+			.set    ("union_station_gateway_cert", serverConfig.unionStationGatewayCert)
+			.set    ("union_station_proxy_address", serverConfig.unionStationProxyAddress)
+			.setStrSet("prestart_urls", serverConfig.prestartURLs);
 		
-		agentsStarter.start(serverConfig.logLevel,
-			(serverConfig.debugLogFile == NULL) ? "" : serverConfig.debugLogFile,
-			getpid(), serverConfig.tempDir,
-			serverConfig.userSwitching,
-			serverConfig.defaultUser, serverConfig.defaultGroup,
-			unixd_config.user_id, unixd_config.group_id,
-			serverConfig.root, serverConfig.defaultRuby, serverConfig.maxPoolSize,
-			serverConfig.maxInstancesPerApp, serverConfig.poolIdleTime,
-			"",
-			serverConfig.analyticsLogUser,
-			serverConfig.analyticsLogGroup,
-			serverConfig.unionStationGatewayAddress,
-			serverConfig.unionStationGatewayPort,
-			serverConfig.unionStationGatewayCert,
-			serverConfig.unionStationProxyAddress,
-			serverConfig.prestartURLs);
+		serverConfig.ctl.addTo(params);
+
+		agentsStarter.start(serverConfig.root, params);
 		
 		// Store some relevant information in the generation directory.
 		string generationPath = agentsStarter.getGeneration()->getPath();

data/ext/common/AgentsStarter.cpp

@@ -1,6 +1,6 @@
 /*
  *  Phusion Passenger - https://www.phusionpassenger.com/
- *  Copyright (c) 2010-2012 Phusion
+ *  Copyright (c) 2010-2013 Phusion
  *
  *  "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.
  *
@@ -23,76 +23,104 @@
  *  THE SOFTWARE.
  */
 #include <oxt/thread.hpp>
-#include "AgentsStarter.h"
-#include "AgentsStarter.hpp"
+#include <set>
 #include <cerrno>
 #include <cstring>
+#include <AgentsStarter.h>
 
 using namespace std;
 using namespace boost;
 using namespace oxt;
 
 
-AgentsStarter *
-agents_starter_new(AgentsStarterType type, char **error_message) {
-	Passenger::AgentsStarter::Type theType;
-	if (type == AS_APACHE) {
-		theType = Passenger::AgentsStarter::APACHE;
-	} else {
-		theType = Passenger::AgentsStarter::NGINX;
+PSG_VariantMap *
+psg_variant_map_new() {
+	return (PSG_VariantMap *) new Passenger::VariantMap();
+}
+
+void
+psg_variant_map_set(PSG_VariantMap *m,
+	const char *name,
+	const char *value,
+	unsigned int value_len)
+{
+	Passenger::VariantMap *vm = (Passenger::VariantMap *) m;
+	vm->set(name, string(value, value_len));
+}
+
+void
+psg_variant_map_set2(PSG_VariantMap *m,
+	const char *name,
+	unsigned int name_len,
+	const char *value,
+	unsigned int value_len)
+{
+	Passenger::VariantMap *vm = (Passenger::VariantMap *) m;
+	vm->set(string(name, name_len), string(value, value_len));
+}
+
+void
+psg_variant_map_set_int(PSG_VariantMap *m,
+	const char *name,
+	int value)
+{
+	Passenger::VariantMap *vm = (Passenger::VariantMap *) m;
+	vm->setInt(name, value);
+}
+
+void
+psg_variant_map_set_bool(PSG_VariantMap *m,
+	const char *name,
+	int value)
+{
+	Passenger::VariantMap *vm = (Passenger::VariantMap *) m;
+	vm->setBool(name, value);
+}
+
+void
+psg_variant_map_set_strset(PSG_VariantMap *m,
+	const char *name,
+	const char **strs,
+	unsigned int count)
+{
+	Passenger::VariantMap *vm = (Passenger::VariantMap *) m;
+	std::set<string> the_set;
+	
+	for (unsigned int i = 0; i < count; i++) {
+		the_set.insert(strs[i]);
 	}
-	return (AgentsStarter *) new Passenger::AgentsStarter(theType);
+	vm->setStrSet(name, the_set);
+}
+
+void
+psg_variant_map_free(PSG_VariantMap *m) {
+	delete (Passenger::VariantMap *) m;
+}
+
+
+PSG_AgentsStarter *
+psg_agents_starter_new(PSG_AgentsStarterType type, char **error_message) {
+	return (PSG_AgentsStarter *) new Passenger::AgentsStarter(type);
 }
 
 int
-agents_starter_start(AgentsStarter *as,
-                     int logLevel, const char *debugLogFile,
-                     pid_t webServerPid,
-                     const char *tempDir, int userSwitching,
-                     const char *defaultUser, const char *defaultGroup,
-                     uid_t webServerWorkerUid, gid_t webServerWorkerGid,
-                     const char *passengerRoot,
-                     const char *defaultRubyCommand, unsigned int maxPoolSize,
-                     unsigned int maxInstancesPerApp,
-                     unsigned int poolIdleTime,
-                     const char *analyticsServer,
-                     const char *analyticsLogUser,
-                     const char *analyticsLogGroup,
-                     const char *unionStationGatewayAddress,
-                     unsigned short unionStationGatewayPort,
-                     const char *unionStationGatewayCert,
-                     const char *unionStationProxyAddress,
-                     const char **prestartURLs, unsigned int prestartURLsCount,
-                     const AfterForkCallback afterFork,
-                     void *callbackArgument,
-                     char **errorMessage)
+psg_agents_starter_start(PSG_AgentsStarter *as,
+	const char *passengerRoot,
+	PSG_VariantMap *extraParams,
+	const PSG_AfterForkCallback afterFork,
+	void *callbackArgument,
+	char **errorMessage)
 {
 	Passenger::AgentsStarter *agentsStarter = (Passenger::AgentsStarter *) as;
 	this_thread::disable_syscall_interruption dsi;
 	try {
 		function<void ()> afterForkFunctionObject;
-		set<string> setOfprestartURLs;
-		unsigned int i;
 		
 		if (afterFork != NULL) {
 			afterForkFunctionObject = boost::bind(afterFork, callbackArgument);
 		}
-		for (i = 0; i < prestartURLsCount; i++) {
-			setOfprestartURLs.insert(prestartURLs[i]);
-		}
-		agentsStarter->start(logLevel, debugLogFile,
-			webServerPid, tempDir, userSwitching,
-			defaultUser, defaultGroup,
-			webServerWorkerUid, webServerWorkerGid,
-			passengerRoot, defaultRubyCommand,
-			maxPoolSize, maxInstancesPerApp, poolIdleTime,
-			analyticsServer,
-			analyticsLogUser, analyticsLogGroup,
-			unionStationGatewayAddress,
-			unionStationGatewayPort,
-			unionStationGatewayCert,
-			unionStationProxyAddress,
-			setOfprestartURLs,
+		agentsStarter->start(passengerRoot,
+			*((Passenger::VariantMap *) extraParams),
 			afterForkFunctionObject);
 		return 1;
 	} catch (const Passenger::SystemException &e) {
@@ -107,7 +135,7 @@ agents_starter_start(AgentsStarter *as,
 }
 
 const char *
-agents_starter_get_request_socket_filename(AgentsStarter *as, unsigned int *size) {
+psg_agents_starter_get_request_socket_filename(PSG_AgentsStarter *as, unsigned int *size) {
 	Passenger::AgentsStarter *agentsStarter = (Passenger::AgentsStarter *) as;
 	if (size != NULL) {
 		*size = agentsStarter->getRequestSocketFilename().size();
@@ -116,7 +144,7 @@ agents_starter_get_request_socket_filename(AgentsStarter *as, unsigned int *size
 }
 
 const char *
-agents_starter_get_request_socket_password(AgentsStarter *as, unsigned int *size) {
+psg_agents_starter_get_request_socket_password(PSG_AgentsStarter *as, unsigned int *size) {
 	Passenger::AgentsStarter *agentsStarter = (Passenger::AgentsStarter *) as;
 	if (size != NULL) {
 		*size = agentsStarter->getRequestSocketPassword().size();
@@ -125,31 +153,31 @@ agents_starter_get_request_socket_password(AgentsStarter *as, unsigned int *size
 }
 
 const char *
-agents_starter_get_server_instance_dir(AgentsStarter *as) {
+psg_agents_starter_get_server_instance_dir(PSG_AgentsStarter *as) {
 	Passenger::AgentsStarter *agentsStarter = (Passenger::AgentsStarter *) as;
 	return agentsStarter->getServerInstanceDir()->getPath().c_str();
 }
 
 const char *
-agents_starter_get_generation_dir(AgentsStarter *as) {
+psg_agents_starter_get_generation_dir(PSG_AgentsStarter *as) {
 	Passenger::AgentsStarter *agentsStarter = (Passenger::AgentsStarter *) as;
 	return agentsStarter->getGeneration()->getPath().c_str();
 }
 
 pid_t
-agents_starter_get_pid(AgentsStarter *as) {
+psg_agents_starter_get_pid(PSG_AgentsStarter *as) {
 	Passenger::AgentsStarter *agentsStarter = (Passenger::AgentsStarter *) as;
 	return agentsStarter->getPid();
 }
 
 void
-agents_starter_detach(AgentsStarter *as) {
+psg_agents_starter_detach(PSG_AgentsStarter *as) {
 	Passenger::AgentsStarter *agentsStarter = (Passenger::AgentsStarter *) as;
 	agentsStarter->detach();
 }
 
 void
-agents_starter_free(AgentsStarter *as) {
+psg_agents_starter_free(PSG_AgentsStarter *as) {
 	Passenger::AgentsStarter *agentsStarter = (Passenger::AgentsStarter *) as;
 	delete agentsStarter;
 }

data/ext/common/AgentsStarter.h

@@ -1,6 +1,6 @@
 /*
  *  Phusion Passenger - https://www.phusionpassenger.com/
- *  Copyright (c) 2010-2012 Phusion
+ *  Copyright (c) 2010-2013 Phusion
  *
  *  "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.
  *
@@ -22,10 +22,9 @@
  *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  *  THE SOFTWARE.
  */
+#ifndef _PASSENGER_AGENTS_STARTER_HPP_
+#define _PASSENGER_AGENTS_STARTER_HPP_
 
-/* C wrappers for Passenger::AgentsStarter. */
-#ifndef _PASSENGER_AGENTS_STARTER_H_
-#define _PASSENGER_AGENTS_STARTER_H_
 
 #include <sys/types.h>
 #include <unistd.h>
@@ -34,49 +33,578 @@
 	extern "C" {
 #endif
 
-
-typedef void AgentsStarter;
-
 typedef enum {
 	AS_APACHE,
 	AS_NGINX
-} AgentsStarterType;
-
-typedef void (*AfterForkCallback)(void *);
-
-AgentsStarter *agents_starter_new(AgentsStarterType type, char **error_message);
-int  agents_starter_start(AgentsStarter *as,
-                          int logLevel, const char *debugLogFile,
-                          pid_t webServerPid,
-                          const char *tempDir, int userSwitching,
-                          const char *defaultUser, const char *defaultGroup,
-                          uid_t webServerWorkerUid, gid_t webServerWorkerGid,
-                          const char *passengerRoot,
-                          const char *defaultRubyCommand, unsigned int maxPoolSize,
-                          unsigned int maxInstancesPerApp,
-                          unsigned int poolIdleTime,
-                          const char *analyticsServer,
-                          const char *analyticsLogUser,
-                          const char *analyticsLogGroup,
-                          const char *unionStationGatewayAddress,
-                          unsigned short unionStationGatewayPort,
-                          const char *unionStationGatewayCert,
-                          const char *unionStationProxyAddress,
-                          const char **prestartURLs, unsigned int prestartURLsCount,
-                          const AfterForkCallback afterFork,
-                          void *callbackArgument,
-                          char **errorMessage);
-const char *agents_starter_get_request_socket_filename(AgentsStarter *as, unsigned int *size);
-const char *agents_starter_get_request_socket_password(AgentsStarter *as, unsigned int *size);
-const char *agents_starter_get_server_instance_dir(AgentsStarter *as);
-const char *agents_starter_get_generation_dir(AgentsStarter *as);
-pid_t       agents_starter_get_pid(AgentsStarter *as);
-void        agents_starter_detach(AgentsStarter *as);
-void        agents_starter_free(AgentsStarter *as);
+} PSG_AgentsStarterType;
+
+typedef void PSG_AgentsStarter;
+typedef void PSG_VariantMap;
+typedef void (*PSG_AfterForkCallback)(void *);
 
+PSG_VariantMap *psg_variant_map_new();
+void psg_variant_map_set(PSG_VariantMap *m,
+	const char *name,
+	const char *value,
+	unsigned int value_len);
+void psg_variant_map_set2(PSG_VariantMap *m,
+	const char *name,
+	unsigned int name_len,
+	const char *value,
+	unsigned int value_len);
+void psg_variant_map_set_int(PSG_VariantMap *m,
+	const char *name,
+	int value);
+void psg_variant_map_set_bool(PSG_VariantMap *m,
+	const char *name,
+	int value);
+void psg_variant_map_set_strset(PSG_VariantMap *m,
+	const char *name,
+	const char **strs,
+	unsigned int count);
+void psg_variant_map_free(PSG_VariantMap *m);
+
+PSG_AgentsStarter *psg_agents_starter_new(PSG_AgentsStarterType type,
+	char **error_message);
+int psg_agents_starter_start(PSG_AgentsStarter *as,
+	const char *passengerRoot,
+	PSG_VariantMap *params,
+	const PSG_AfterForkCallback afterFork,
+	void *callbackArgument,
+	char **errorMessage);
+const char *psg_agents_starter_get_request_socket_filename(PSG_AgentsStarter *as, unsigned int *size);
+const char *psg_agents_starter_get_request_socket_password(PSG_AgentsStarter *as, unsigned int *size);
+const char *psg_agents_starter_get_server_instance_dir(PSG_AgentsStarter *as);
+const char *psg_agents_starter_get_generation_dir(PSG_AgentsStarter *as);
+pid_t       psg_agents_starter_get_pid(PSG_AgentsStarter *as);
+void        psg_agents_starter_detach(PSG_AgentsStarter *as);
+void        psg_agents_starter_free(PSG_AgentsStarter *as);
 
 #ifdef __cplusplus
-	}
+	} /* extern "C" */
 #endif
 
-#endif /* _PASSENGER_AGENTS_STARTER_H_ */
+
+#ifdef __cplusplus
+
+#include <boost/function.hpp>
+#include <oxt/system_calls.hpp>
+#include <oxt/backtrace.hpp>
+#include <string>
+#include <vector>
+#include <set>
+
+#include <signal.h>
+
+#include <Constants.h>
+#include <FileDescriptor.h>
+#include <MessageClient.h>
+#include <ServerInstanceDir.h>
+#include <Exceptions.h>
+#include <ResourceLocator.h>
+#include <Logging.h>
+#include <Utils.h>
+#include <Utils/IOUtils.h>
+#include <Utils/MessageIO.h>
+#include <Utils/Timer.h>
+#include <Utils/ScopeGuard.h>
+#include <Utils/VariantMap.h>
+
+namespace Passenger {
+
+using namespace std;
+using namespace boost;
+using namespace oxt;
+
+/**
+ * Utility class for starting various Phusion Passenger agents through the watchdog.
+ */
+class AgentsStarter {
+private:
+	PSG_AgentsStarterType type;
+
+	/** The watchdog's PID. Equals 0 if the watchdog hasn't been started yet
+	 * or if detach() is called. */
+	pid_t pid;
+
+	/******* Information about the started services. Only valid when pid != 0. *******/
+	
+	 /** The watchdog's feedback file descriptor. */
+	FileDescriptor feedbackFd;
+	
+	/** The helper agent's request socket filename and its password. This socket
+	 * is for serving SCGI requests. */
+	string requestSocketFilename;
+	string requestSocketPassword;
+	
+	/** The socket on which the helper agent listens for administration commands,
+	 * and the corresponding password for the "web_server" account, which has the
+	 * authorization to shutdown the helper agent.
+	 */
+	string helperAgentAdminSocketAddress;
+	string helperAgentExitPassword;
+
+	/** The logging agent's socket address and its password. */
+	string loggingSocketAddress;
+	string loggingSocketPassword;
+	
+	/** The server instance dir and generation dir of the agents. */
+	ServerInstanceDirPtr serverInstanceDir;
+	/** The generation dir of the agents. */
+	ServerInstanceDir::GenerationPtr generation;
+	
+	/**
+	 * Safely dup2() the given file descriptor to 3 (FEEDBACK_FD).
+	 */
+	void installFeedbackFd(const FileDescriptor &fd) {
+		if (fd != FEEDBACK_FD && syscalls::dup2(fd, FEEDBACK_FD) == -1) {
+			int e = errno;
+			try {
+				writeArrayMessage(fd,
+					"system error",
+					"dup2() failed",
+					toString(e).c_str(),
+					NULL);
+				_exit(1);
+			} catch (...) {
+				fprintf(stderr, "Passenger AgentsStarter: dup2() failed: %s (%d)\n",
+					strerror(e), e);
+				fflush(stderr);
+				_exit(1);
+			}
+		}
+	}
+	
+	/**
+	 * Call this if the watchdog seems to have crashed. This function will try
+	 * to determine whether the watchdog is still running, whether it crashed
+	 * with a signal, etc. If it has detected that the watchdog is no longer running
+	 * then it will set `pid` to -1.
+	 */
+	void inspectWatchdogCrashReason(pid_t &pid) {
+		this_thread::disable_interruption di;
+		this_thread::disable_syscall_interruption dsi;
+		int ret, status;
+		
+		/* Upon noticing that something went wrong, the watchdog
+		 * or its subprocesses might still be writing out an error
+		 * report, so we wait a while before killing the watchdog.
+		 */
+		ret = timedWaitPid(pid, &status, 5000);
+		if (ret == 0) {
+			/* Looks like the watchdog didn't crash and is still running. */
+			throw RuntimeException(
+				"Unable to start the Phusion Passenger watchdog: "
+				"it froze during startup and reported an unknown error");
+		} else if (ret != -1 && WIFSIGNALED(status)) {
+			/* Looks like a crash which caused a signal. */
+			pid = -1;
+			throw RuntimeException(
+				"Unable to start the Phusion Passenger watchdog: "
+				"it seems to have been killed with signal " +
+				getSignalName(WTERMSIG(status)) + " during startup");
+		} else if (ret == -1) {
+			/* Looks like it exited for a different reason and has no exit code. */
+			pid = -1;
+			throw RuntimeException(
+				"Unable to start the Phusion Passenger watchdog: "
+				"it seems to have crashed during startup for an unknown reason");
+		} else {
+			/* Looks like it exited for a different reason, but has an exit code. */
+			pid = -1;
+			throw RuntimeException(
+				"Unable to start the Phusion Passenger watchdog: "
+				"it seems to have crashed during startup for an unknown reason, "
+				"with exit code " + toString(WEXITSTATUS(status)));
+		}
+	}
+	
+	static void killProcessGroupAndWait(pid_t *pid, unsigned long long timeout = 0) {
+		if (*pid != -1 && (timeout == 0 || timedWaitPid(*pid, NULL, timeout) <= 0)) {
+			this_thread::disable_syscall_interruption dsi;
+			syscalls::killpg(*pid, SIGKILL);
+			syscalls::waitpid(*pid, NULL, 0);
+			*pid = -1;
+		}
+	}
+	
+	/**
+	 * Behaves like `waitpid(pid, status, WNOHANG)`, but waits at most
+	 * `timeout` miliseconds for the process to exit.
+	 */
+	static int timedWaitPid(pid_t pid, int *status, unsigned long long timeout) {
+		Timer timer;
+		int ret;
+		
+		do {
+			ret = syscalls::waitpid(pid, status, WNOHANG);
+			if (ret > 0 || ret == -1) {
+				return ret;
+			} else {
+				syscalls::usleep(10000);
+			}
+		} while (timer.elapsed() < timeout);
+		return 0; // timed out
+	}
+	
+	/**
+	 * Gracefully shutdown an agent process by sending an exit command to its socket.
+	 * Returns whether the agent has successfully processed the exit command.
+	 * Any exceptions are caught and will cause false to be returned.
+	 */
+	bool gracefullyShutdownAgent(const string &address, const string &username,
+		const string &password)
+	{
+		try {
+			MessageClient client;
+			vector<string> args;
+			
+			client.connect(address, username, password);
+			client.write("exit", NULL);
+			return client.read(args) && args[0] == "Passed security" &&
+			       client.read(args) && args[0] == "exit command received";
+		} catch (const SystemException &) {
+		} catch (const IOException &) {
+		} catch (const SecurityException &) {
+		}
+		return false;
+	}
+
+	string findUnionStationGatewayCert(const ResourceLocator &locator,
+		const VariantMap &params) const
+	{
+		string value = params.get("union_station_gateway_cert", false);
+		if (value.empty()) {
+			return locator.getResourcesDir() + "/union_station_gateway.crt";
+		} else {
+			return value;
+		}
+	}
+	
+public:
+	/**
+	 * Construct a AgentsStarter object. The watchdog and the agents
+	 * aren't started yet until you call start().
+	 *
+	 * @param type Whether one wants to start the Apache or the Nginx helper agent.
+	 */
+	AgentsStarter(PSG_AgentsStarterType type) {
+		this->type = type;
+		pid = 0;
+	}
+	
+	~AgentsStarter() {
+		if (pid != 0) {
+			this_thread::disable_syscall_interruption dsi;
+			bool cleanShutdown = gracefullyShutdownAgent(helperAgentAdminSocketAddress,
+				"_web_server", helperAgentExitPassword);
+			cleanShutdown = cleanShutdown &&
+				gracefullyShutdownAgent(loggingSocketAddress,
+					"logging", loggingSocketPassword);
+			
+			/* Send a message down the feedback fd to tell the watchdog
+			 * Whether this is a clean shutdown. Closing the fd without
+			 * sending anything also indicates an unclean shutdown,
+			 * but we send a byte anyway in case there are other processes
+			 * who have the fd open.
+			 */
+			if (cleanShutdown) {
+				syscalls::write(feedbackFd, "c", 1);
+			} else {
+				syscalls::write(feedbackFd, "u", 1);
+			}
+			
+			/* If we failed to send an exit command to one of the agents then we have
+			 * to forcefully kill all agents now because otherwise one of them might
+			 * never exit. We do this by closing the feedback fd without sending a
+			 * random byte, to indicate that this is an abnormal shutdown. The watchdog
+			 * will then kill all agents.
+			 */
+			
+			feedbackFd.close();
+			syscalls::waitpid(pid, NULL, 0);
+		}
+	}
+	
+	/**
+	 * Returns the type as was passed to the constructor.
+	 */
+	PSG_AgentsStarterType getType() const {
+		return type;
+	}
+	
+	/**
+	 * Returns the watchdog's PID. Equals 0 if the watchdog hasn't been started yet
+	 * or if detach() is called.
+	 */
+	pid_t getPid() const {
+		return pid;
+	}
+	
+	// The 'const string &' here is on purpose. The C getter functions
+	// return the string pointer directly.
+	const string &getRequestSocketFilename() const {
+		return requestSocketFilename;
+	}
+	
+	const string &getRequestSocketPassword() const {
+		return requestSocketPassword;
+	}
+	
+	string getHelperAgentAdminSocketFilename() const {
+		return parseUnixSocketAddress(helperAgentAdminSocketAddress);
+	}
+	
+	string getHelperAgentExitPassword() const {
+		return helperAgentExitPassword;
+	}
+	
+	string getLoggingSocketAddress() const {
+		return loggingSocketAddress;
+	}
+	
+	string getLoggingSocketPassword() const {
+		return loggingSocketPassword;
+	}
+	
+	ServerInstanceDirPtr getServerInstanceDir() const {
+		return serverInstanceDir;
+	}
+	
+	ServerInstanceDir::GenerationPtr getGeneration() const {
+		return generation;
+	}
+	
+	/**
+	 * Start the agents through the watchdog.
+	 *
+	 * @throws SystemException Something went wrong.
+	 * @throws IOException Something went wrong while communicating with one
+	 *                     of the agents during its initialization phase.
+	 * @throws RuntimeException Something went wrong.
+	 */
+	void start(const string &passengerRoot,
+		const VariantMap &extraParams = VariantMap(),
+		const function<void ()> &afterFork = function<void ()>())
+	{
+		TRACE_POINT();
+		this_thread::disable_interruption di;
+		this_thread::disable_syscall_interruption dsi;
+		ResourceLocator locator(passengerRoot);
+		string realUnionStationGatewayCert = findUnionStationGatewayCert(locator, extraParams);
+		string watchdogFilename = locator.getAgentsDir() + "/PassengerWatchdog";
+		SocketPair fds;
+		int e;
+		pid_t pid;
+
+		VariantMap params;
+		params
+			.set    ("web_server_type", type == AS_APACHE ? "apache" : "nginx")
+			.setPid ("web_server_pid",  getpid())
+			.set    ("passenger_root",  passengerRoot)
+			.setInt ("log_level",       getLogLevel())
+			.set    ("temp_dir",        getSystemTempDir());
+		extraParams.addTo(params);
+
+		// .setUid ("web_server_worker_uid", webServerWorkerUid)
+		// .setGid ("web_server_worker_gid", webServerWorkerGid)
+		// .set    ("debug_log_file",  debugLogFile)
+		// .set    ("temp_dir",        tempDir.empty() ? getSystemTempDir() : tempDir)
+		// .setBool("user_switching",  userSwitching)
+		// .set    ("default_user",    defaultUser)
+		// .set    ("default_group",   defaultGroup)
+		// .set    ("default_ruby",    defaultRubyCommand)
+		// .setInt ("max_pool_size",   maxPoolSize)
+		// .setInt ("max_instances_per_app",     maxInstancesPerApp)
+		/*
+			.setInt ("pool_idle_time",            poolIdleTime)
+			.set    ("analytics_server",          analyticsServer)
+			.set    ("analytics_log_user",        analyticsLogUser)
+			.set    ("analytics_log_group",       analyticsLogGroup)
+			.set    ("union_station_gateway_address",  unionStationGatewayAddress)
+			.setInt ("union_station_gateway_port", unionStationGatewayPort)
+			.set    ("union_station_gateway_cert", realUnionStationGatewayCert)
+			.set    ("union_station_proxy_address", unionStationProxyAddress)
+			.set    ("prestart_urls",   serializePrestartURLs(prestartURLs));
+		*/
+		
+		fds = createUnixSocketPair();
+		pid = syscalls::fork();
+		if (pid == 0) {
+			// Child
+			
+			/* Become the session leader so that Apache can't kill the
+			 * watchdog with killpg() during shutdown, so that a
+			 * Ctrl-C only affects the web server, and so that
+			 * we can kill all of our subprocesses in a single killpg().
+			 */
+			setsid();
+			
+			// Make sure the feedback fd is 3 and close all file descriptors
+			// except stdin, stdout, stderr and 3.
+			syscalls::close(fds[0]);
+			installFeedbackFd(fds[1]);
+			closeAllFileDescriptors(FEEDBACK_FD);
+			
+			/* We don't know how the web server or the environment affect
+			 * signal handlers and the signal mask, so reset this stuff
+			 * just in case.
+			 */
+			resetSignalHandlersAndMask();
+			
+			if (afterFork) {
+				afterFork();
+			}
+			
+			execl(watchdogFilename.c_str(), "PassengerWatchdog", (char *) 0);
+			e = errno;
+			try {
+				writeArrayMessage(FEEDBACK_FD,
+					"exec error",
+					toString(e).c_str(),
+					NULL);
+				_exit(1);
+			} catch (...) {
+				fprintf(stderr, "Passenger AgentsStarter: could not execute %s: %s (%d)\n",
+					watchdogFilename.c_str(), strerror(e), e);
+				fflush(stderr);
+				_exit(1);
+			}
+		} else if (pid == -1) {
+			// Error
+			e = errno;
+			throw SystemException("Cannot fork a new process", e);
+		} else {
+			// Parent
+			UPDATE_TRACE_POINT();
+			FileDescriptor feedbackFd = fds[0];
+			vector<string> args;
+			bool result;
+			
+			ScopeGuard guard(boost::bind(&AgentsStarter::killProcessGroupAndWait, &pid, 0));
+			fds[1].close();
+			
+			
+			/****** Send arguments to watchdog through the feedback channel ******/
+			
+			UPDATE_TRACE_POINT();
+			/* Here we don't care about EPIPE and ECONNRESET errors. The watchdog
+			 * could have sent an error message over the feedback fd without
+			 * reading the arguments. We'll notice that later.
+			 */
+			try {
+				params.writeToFd(feedbackFd);
+			} catch (const SystemException &e) {
+				if (e.code() != EPIPE && e.code() != ECONNRESET) {
+					inspectWatchdogCrashReason(pid);
+				}
+			}
+			
+			
+			/****** Read agents information report ******/
+			
+			this_thread::restore_interruption ri(di);
+			this_thread::restore_syscall_interruption rsi(dsi);
+			UPDATE_TRACE_POINT();
+			
+			try {
+				result = readArrayMessage(feedbackFd, args);
+			} catch (const SystemException &ex) {
+				if (ex.code() == ECONNRESET) {
+					inspectWatchdogCrashReason(pid);
+				} else {
+					killProcessGroupAndWait(&pid, 5000);
+					guard.clear();
+					throw SystemException("Unable to start the Phusion Passenger watchdog: "
+						"unable to read its startup information report",
+						ex.code());
+				}
+			}
+			if (!result) {
+				UPDATE_TRACE_POINT();
+				inspectWatchdogCrashReason(pid);
+			}
+			
+			if (args[0] == "Agents information") {
+				if ((args.size() - 1) % 2 != 0) {
+					throw RuntimeException("Unable to start the Phusion Passenger watchdog "
+						"because it sent an invalid startup information report (the number "
+						"of items is not an even number)");
+				}
+
+				VariantMap info;
+				for (unsigned i = 1; i < args.size(); i += 2) {
+					const string &key = args[i];
+					const string &value = args[i + 1];
+					info.set(key, value);
+				}
+
+				this->pid        = pid;
+				this->feedbackFd = feedbackFd;
+				requestSocketFilename   = info.get("request_socket_filename");
+				requestSocketPassword   = info.get("request_socket_password");
+				helperAgentAdminSocketAddress = info.get("helper_agent_admin_socket_address");
+				helperAgentExitPassword       = info.get("helper_agent_exit_password");
+				serverInstanceDir = make_shared<ServerInstanceDir>(info.get("server_instance_dir"), false);
+				generation        = serverInstanceDir->getGeneration(info.getInt("generation"));
+				loggingSocketAddress  = info.get("logging_socket_address");
+				loggingSocketPassword = info.get("logging_socket_password");
+				guard.clear();
+			} else if (args[0] == "Watchdog startup error") {
+				killProcessGroupAndWait(&pid, 5000);
+				guard.clear();
+				throw RuntimeException("Unable to start the Phusion Passenger watchdog "
+					"because it encountered the following error during startup: " +
+					args[1]);
+			} else if (args[0] == "system error") {
+				killProcessGroupAndWait(&pid, 5000);
+				guard.clear();
+				throw SystemException(args[1], atoi(args[2]));
+			} else if (args[0] == "exec error") {
+				e = atoi(args[1]);
+				killProcessGroupAndWait(&pid, 5000);
+				guard.clear();
+				if (e == ENOENT) {
+					string passengerRootConfig;
+					if (type == AS_APACHE) {
+						passengerRootConfig = "PassengerRoot";
+					} else {
+						passengerRootConfig = "passenger_root";
+					}
+					throw RuntimeException("Unable to start the Phusion Passenger watchdog "
+						"because its executable (" + watchdogFilename + ") does "
+						"not exist. This probably means that your Phusion Passenger "
+						"installation is broken or incomplete, or that your '" +
+						passengerRootConfig + "' directive is set to the wrong value. "
+						"Please reinstall Phusion Passenger or fix your '" +
+						passengerRootConfig + "' directive, whichever is applicable.");
+				} else {
+					throw SystemException("Unable to start the Phusion Passenger watchdog (" +
+						watchdogFilename + ")", e);
+				}
+			} else {
+				UPDATE_TRACE_POINT();
+				killProcessGroupAndWait(&pid, 5000);
+				guard.clear();
+				throw RuntimeException("One of the Passenger agents sent an unknown feedback message '" + args[0] + "'");
+			}
+		}
+	}
+	
+	/**
+	 * Close any file descriptors that this object has, and make it so that the destructor
+	 * doesn't try to shut down the agents.
+	 *
+	 * @post getPid() == 0
+	 */
+	void detach() {
+		feedbackFd.close();
+		pid = 0;
+	}
+};
+
+} // namespace Passenger
+
+#endif /* __cplusplus */
+
+#endif /* _PASSENGER_AGENTS_STARTER_HPP_ */