00001 /* 00002 * Phusion Passenger - http://www.modrails.com/ 00003 * Copyright (c) 2010 Phusion 00004 * 00005 * "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui. 00006 * 00007 * Permission is hereby granted, free of charge, to any person obtaining a copy 00008 * of this software and associated documentation files (the "Software"), to deal 00009 * in the Software without restriction, including without limitation the rights 00010 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 00011 * copies of the Software, and to permit persons to whom the Software is 00012 * furnished to do so, subject to the following conditions: 00013 * 00014 * The above copyright notice and this permission notice shall be included in 00015 * all copies or substantial portions of the Software. 00016 * 00017 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 00018 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00019 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 00020 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 00021 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 00022 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 00023 * THE SOFTWARE. 00024 */ 00025 #ifndef _PASSENGER_UTILS_H_ 00026 #define _PASSENGER_UTILS_H_ 00027 00028 #include <boost/shared_ptr.hpp> 00029 #include <boost/function.hpp> 00030 #include <sys/types.h> 00031 #include <sys/stat.h> 00032 #include <string> 00033 #include <vector> 00034 #include <utility> 00035 #include <sstream> 00036 #include <cstdio> 00037 #include <climits> 00038 #include <cstdlib> 00039 #include <cstring> 00040 #include <errno.h> 00041 #include <unistd.h> 00042 #include "StaticString.h" 00043 #include "Exceptions.h" 00044 00045 namespace Passenger { 00046 00047 using namespace std; 00048 using namespace boost; 00049 00050 static const uid_t USER_NOT_GIVEN = (uid_t) -1; 00051 static const gid_t GROUP_NOT_GIVEN = (gid_t) -1; 00052 00053 typedef struct CachedFileStat CachedFileStat; 00054 class ResourceLocator; 00055 00056 /** Enumeration which indicates what kind of file a file is. */ 00057 typedef enum { 00058 /** The file doesn't exist. */ 00059 FT_NONEXISTANT, 00060 /** A regular file or a symlink to a regular file. */ 00061 FT_REGULAR, 00062 /** A directory. */ 00063 FT_DIRECTORY, 00064 /** Something else, e.g. a pipe or a socket. */ 00065 FT_OTHER 00066 } FileType; 00067 00068 /** 00069 * Convenience shortcut for creating a <tt>shared_ptr</tt>. 00070 * Instead of: 00071 * @code 00072 * shared_ptr<Foo> foo; 00073 * ... 00074 * foo = shared_ptr<Foo>(new Foo()); 00075 * @endcode 00076 * one can write: 00077 * @code 00078 * shared_ptr<Foo> foo; 00079 * ... 00080 * foo = ptr(new Foo()); 00081 * @endcode 00082 * 00083 * @param pointer The item to put in the shared_ptr object. 00084 * @ingroup Support 00085 */ 00086 template<typename T> shared_ptr<T> 00087 ptr(T *pointer) { 00088 return shared_ptr<T>(pointer); 00089 } 00090 00091 /** 00092 * Check whether the specified file exists. 00093 * 00094 * @param filename The filename to check. 00095 * @param cstat A CachedFileStat object, if you want to use cached statting. 00096 * @param throttleRate A throttle rate for cstat. Only applicable if cstat is not NULL. 00097 * @return Whether the file exists. 00098 * @throws FileSystemException Unable to check because of a filesystem error. 00099 * @throws TimeRetrievalException 00100 * @throws boost::thread_interrupted 00101 * @ingroup Support 00102 */ 00103 bool fileExists(const StaticString &filename, CachedFileStat *cstat = 0, 00104 unsigned int throttleRate = 0); 00105 00106 /** 00107 * Check whether 'filename' exists and what kind of file it is. 00108 * 00109 * @param filename The filename to check. 00110 * @param mstat A CachedFileStat object, if you want to use cached statting. 00111 * @param throttleRate A throttle rate for cstat. Only applicable if cstat is not NULL. 00112 * @return The file type. 00113 * @throws FileSystemException Unable to check because of a filesystem error. 00114 * @throws TimeRetrievalException 00115 * @throws boost::thread_interrupted 00116 * @ingroup Support 00117 */ 00118 FileType getFileType(const StaticString &filename, CachedFileStat *cstat = 0, 00119 unsigned int throttleRate = 0); 00120 00121 /** 00122 * Create the given file with the given contents, permissions and ownership. 00123 * This function does not leave behind junk files: if the ownership cannot be set 00124 * or if not all data can be written then then the file will be deleted. 00125 * 00126 * @param filename The file to create. 00127 * @param contents The contents to write to the file. 00128 * @param permissions The desired file permissions. 00129 * @param owner The desired file owner. Specify USER_NOT_GIVEN if you want to use the current 00130 * process's owner as the file owner. 00131 * @param group The desired file group. Specify GROUP_NOT_GIVEN if you want to use the current 00132 * process's group as the file group. 00133 * @param overwrite Whether to overwrite the file if it exists. If set to false 00134 * and the file exists then nothing will happen. 00135 * @throws FileSystemException Something went wrong. 00136 * @ingroup Support 00137 */ 00138 void createFile(const string &filename, const StaticString &contents, 00139 mode_t permissions = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH, 00140 uid_t owner = USER_NOT_GIVEN, gid_t group = GROUP_NOT_GIVEN, 00141 bool overwrite = true); 00142 00143 /** 00144 * Returns a canonical version of the specified path. All symbolic links 00145 * and relative path elements are resolved. 00146 * 00147 * @throws FileSystemException Something went wrong. 00148 * @ingroup Support 00149 */ 00150 string canonicalizePath(const string &path); 00151 00152 /** 00153 * If <em>path</em> refers to a symlink, then this function resolves the 00154 * symlink for 1 level. That is, if the symlink points to another symlink, 00155 * then the other symlink will not be resolved. The resolved path is returned. 00156 * 00157 * If the symlink doesn't point to an absolute path, then this function will 00158 * prepend <em>path</em>'s directory to the result. 00159 * 00160 * If <em>path</em> doesn't refer to a symlink then this method will return 00161 * <em>path</em>. 00162 * 00163 * @throws FileSystemException Something went wrong. 00164 * @ingroup Support 00165 */ 00166 string resolveSymlink(const string &path); 00167 00168 /** 00169 * Given a path, extracts its directory name. 00170 * 00171 * @ingroup Support 00172 */ 00173 string extractDirName(const StaticString &path); 00174 00175 /** 00176 * Given a path, extracts its base name. 00177 * 00178 * @ingroup Support 00179 */ 00180 string extractBaseName(const StaticString &path); 00181 00182 /** 00183 * Escape the given raw string into an XML value. 00184 * 00185 * @throws std::bad_alloc Something went wrong. 00186 * @ingroup Support 00187 */ 00188 string escapeForXml(const string &input); 00189 00190 /** 00191 * Returns the username of the user that the current process is running as. 00192 * If the user has no associated username, then "UID xxxx" is returned, 00193 * where xxxx is the current UID. 00194 */ 00195 string getProcessUsername(); 00196 00197 /** 00198 * Converts a mode string into a mode_t value. 00199 * 00200 * At this time only the symbolic mode strings are supported, e.g. something like looks 00201 * this: "u=rwx,g=w,o=rx". The grammar is as follows: 00202 * @code 00203 * mode ::= (clause ("," clause)*)? 00204 * clause ::= who "=" permission* 00205 * who ::= "u" | "g" | "o" 00206 * permission ::= "r" | "w" | "x" | "s" 00207 * @endcode 00208 * 00209 * Notes: 00210 * - The mode value starts with 0. So if you specify "u=rwx", then the group and world 00211 * permissions will be empty (set to 0). 00212 * - The "s" permission is only allowed for who == "u" or who == "g". 00213 * - The return value does not depend on the umask. 00214 * 00215 * @throws InvalidModeStringException The mode string cannot be parsed. 00216 */ 00217 mode_t parseModeString(const StaticString &mode); 00218 00219 /** 00220 * Return the path name for the directory in which the system stores general 00221 * temporary files. This is usually "/tmp", but might be something else depending 00222 * on some environment variables. 00223 * 00224 * @ensure result != NULL 00225 * @ingroup Support 00226 */ 00227 const char *getSystemTempDir(); 00228 00229 /* Create a temporary directory for storing Phusion Passenger instance-specific 00230 * temp files, such as temporarily buffered uploads, sockets for backend 00231 * processes, etc. 00232 * The directory that will be created is the one returned by 00233 * <tt>getPassengerTempDir(false, parentDir)</tt>. This call stores the path to 00234 * this temp directory in an internal variable, so that subsequent calls to 00235 * getPassengerTempDir() will return the same path. 00236 * 00237 * The created temp directory will have several subdirectories: 00238 * - webserver_private - for storing the web server's buffered uploads. 00239 * - info - for storing files that allow external tools to query information 00240 * about a running Phusion Passenger instance. 00241 * - backends - for storing Unix sockets created by backend processes. 00242 * - master - for storing files such as the Passenger HelperServer socket. 00243 * 00244 * If a (sub)directory already exists, then it will not result in an error. 00245 * 00246 * The <em>userSwitching</em> and <em>lowestUser</em> arguments passed to 00247 * this method are used for determining the optimal permissions for the 00248 * (sub)directories. The permissions will be set as tightly as possible based 00249 * on the values. The <em>workerUid</em> and <em>workerGid</em> arguments 00250 * will be used for determining the owner of certain subdirectories. 00251 * 00252 * @note You should only call this method inside the web server's master 00253 * process. In case of Apache, this is the Apache control process, 00254 * the one that tends to run as root. This is because this function 00255 * will set directory permissions and owners/groups, which may require 00256 * root privileges. 00257 * 00258 * @param parentDir The directory under which the Phusion Passenger-specific 00259 * temp directory should be created. This argument may be the 00260 * empty string, in which case getSystemTempDir() will be used 00261 * as the parent directory. 00262 * @param userSwitching Whether user switching is turned on. 00263 * @param lowestUser The user that the spawn manager and the pool server will 00264 * run as, if user switching is turned off. 00265 * @param workerUid The UID that the web server's worker processes are running 00266 * as. On Apache, this is the UID that's associated with the 00267 * 'User' directive. 00268 * @param workerGid The GID that the web server's worker processes are running 00269 * as. On Apache, this is the GID that's associated with the 00270 * 'Group' directive. 00271 * @throws IOException Something went wrong. 00272 * @throws SystemException Something went wrong. 00273 * @throws FileSystemException Something went wrong. 00274 */ 00275 /* void createPassengerTempDir(const string &parentDir, bool userSwitching, 00276 const string &lowestUser, 00277 uid_t workerUid, gid_t workerGid); */ 00278 00279 /** 00280 * Create the directory at the given path, creating intermediate directories 00281 * if necessary. The created directories' permissions are exactly as specified 00282 * by the 'mode' parameter (i.e. the umask will be ignored). You can specify 00283 * this directory's owner and group through the 'owner' and 'group' parameters. 00284 * A value of USER_NOT_GIVEN for 'owner' and/or GROUP_NOT_GIVEN 'group' means 00285 * that the owner/group should not be changed. 00286 * 00287 * If 'path' already exists, then nothing will happen. 00288 * 00289 * @param mode A mode string, as supported by parseModeString(). 00290 * @throws FileSystemException Something went wrong. 00291 * @throws InvalidModeStringException The mode string cannot be parsed. 00292 */ 00293 void makeDirTree(const string &path, const StaticString &mode = "u=rwx,g=,o=", 00294 uid_t owner = USER_NOT_GIVEN, gid_t group = GROUP_NOT_GIVEN); 00295 00296 /** 00297 * Remove an entire directory tree recursively. If the directory doesn't exist then this 00298 * function does nothing. 00299 * 00300 * @throws FileSystemException Something went wrong. 00301 */ 00302 void removeDirTree(const string &path); 00303 00304 /** 00305 * Check whether the specified directory is a valid Ruby on Rails 00306 * application root directory. 00307 * 00308 * @param cstat A CachedFileStat object, if you want to use cached statting. 00309 * @param throttleRate A throttle rate for cstat. Only applicable if cstat is not NULL. 00310 * @throws FileSystemException Unable to check because of a system error. 00311 * @throws TimeRetrievalException 00312 * @throws boost::thread_interrupted 00313 * @ingroup Support 00314 */ 00315 bool verifyRailsDir(const string &dir, CachedFileStat *cstat = 0, 00316 unsigned int throttleRate = 0); 00317 00318 /** 00319 * Check whether the specified directory is a valid Rack application 00320 * root directory. 00321 * 00322 * @param cstat A CachedFileStat object, if you want to use cached statting. 00323 * @param throttleRate A throttle rate for cstat. Only applicable if cstat is not NULL. 00324 * @throws FileSystemException Unable to check because of a filesystem error. 00325 * @throws TimeRetrievalException 00326 * @throws boost::thread_interrupted 00327 * @ingroup Support 00328 */ 00329 bool verifyRackDir(const string &dir, CachedFileStat *cstat = 0, 00330 unsigned int throttleRate = 0); 00331 00332 /** 00333 * Check whether the specified directory is a valid WSGI application 00334 * root directory. 00335 * 00336 * @param cstat A CachedFileStat object, if you want to use cached statting. 00337 * @param throttleRate A throttle rate for cstat. Only applicable if cstat is not NULL. 00338 * @throws FileSystemException Unable to check because of a filesystem error. 00339 * @throws TimeRetrievalException 00340 * @throws boost::thread_interrupted 00341 * @ingroup Support 00342 */ 00343 bool verifyWSGIDir(const string &dir, CachedFileStat *cstat = 0, 00344 unsigned int throttleRate = 0); 00345 00346 void prestartWebApps(const ResourceLocator &locator, const string &serializedprestartURLs); 00347 00348 /** 00349 * Runs the given function and catches any tracable_exceptions. Upon catching such an exception, 00350 * its message and backtrace will be printed. If toAbort is true then it will call abort(), 00351 * otherwise the exception is swallowed. 00352 * thread_interrupted and all other exceptions are silently propagated. 00353 */ 00354 void runAndPrintExceptions(const function<void ()> &func, bool toAbort); 00355 void runAndPrintExceptions(const function<void ()> &func); 00356 00357 /** 00358 * Returns the system's host name. 00359 * 00360 * @throws SystemException The host name cannot be retrieved. 00361 */ 00362 string getHostName(); 00363 00364 /** 00365 * Convert a signal number to its associated name. 00366 */ 00367 string getSignalName(int sig); 00368 00369 /** 00370 * Resets the current process's signal handler disposition and signal mask 00371 * to default values. One should call this every time one forks a child process; 00372 * non-default signal masks/handler dispositions can cause all kinds of weird quirks, 00373 * like waitpid() malfunctioning on OS X. 00374 * 00375 * This function is async-signal safe. 00376 */ 00377 void resetSignalHandlersAndMask(); 00378 00379 /** 00380 * Close all file descriptors that are higher than <em>lastToKeepOpen</em>. 00381 * This function is async-signal safe. But make sure there are no other 00382 * threads running that might open file descriptors! 00383 */ 00384 void closeAllFileDescriptors(int lastToKeepOpen); 00385 00386 00387 /** 00388 * Represents a buffered upload file. 00389 * 00390 * @ingroup Support 00391 */ 00392 class BufferedUpload { 00393 public: 00394 /** The file handle. */ 00395 FILE *handle; 00396 00397 /** 00398 * Create an empty upload bufer file, and open it for reading and writing. 00399 * 00400 * @throws SystemException Something went wrong. 00401 */ 00402 BufferedUpload(const string &dir, const char *identifier = "temp") { 00403 char templ[PATH_MAX]; 00404 int fd; 00405 00406 snprintf(templ, sizeof(templ), "%s/%s.XXXXXX", dir.c_str(), identifier); 00407 templ[sizeof(templ) - 1] = '\0'; 00408 fd = mkstemp(templ); 00409 if (fd == -1) { 00410 char message[1024]; 00411 int e = errno; 00412 00413 snprintf(message, sizeof(message), "Cannot create a temporary file '%s'", templ); 00414 message[sizeof(message) - 1] = '\0'; 00415 throw SystemException(message, e); 00416 } 00417 00418 /* We use a POSIX trick here: the file's permissions are set to "u=,g=,o=" 00419 * and the file is deleted immediately from the filesystem, while we 00420 * keep its file handle open. The result is that no other processes 00421 * will be able to access this file's contents anymore, except us. 00422 * We now have an anonymous disk-backed buffer. 00423 */ 00424 fchmod(fd, 0000); 00425 unlink(templ); 00426 00427 handle = fdopen(fd, "w+"); 00428 } 00429 00430 ~BufferedUpload() { 00431 fclose(handle); 00432 } 00433 }; 00434 00435 } // namespace Passenger 00436 00437 #endif /* _PASSENGER_UTILS_H_ */ 00438