| 1 | /* Licensed to the Apache Software Foundation (ASF) under one or more |
| 2 | * contributor license agreements. See the NOTICE file distributed with |
| 3 | * this work for additional information regarding copyright ownership. |
| 4 | * The ASF licenses this file to You under the Apache License, Version 2.0 |
| 5 | * (the "License"); you may not use this file except in compliance with |
| 6 | * the License. You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | /* The purpose of this file is to store the code that MOST mpm's will need |
| 18 | * this does not mean a function only goes into this file if every MPM needs |
| 19 | * it. It means that if a function is needed by more than one MPM, and |
| 20 | * future maintenance would be served by making the code common, then the |
| 21 | * function belongs here. |
| 22 | * |
| 23 | * This is going in src/main because it is not platform specific, it is |
| 24 | * specific to multi-process servers, but NOT to Unix. Which is why it |
| 25 | * does not belong in src/os/unix |
| 26 | */ |
| 27 | |
| 28 | /** |
| 29 | * @file mpm_common.h |
| 30 | * @brief Multi-Processing Modules functions |
| 31 | * |
| 32 | * @defgroup APACHE_MPM Multi-Processing Modules |
| 33 | * @ingroup APACHE |
| 34 | * @{ |
| 35 | */ |
| 36 | |
| 37 | #ifndef APACHE_MPM_COMMON_H |
| 38 | #define APACHE_MPM_COMMON_H |
| 39 | |
| 40 | #include "ap_config.h" |
| 41 | |
| 42 | #if APR_HAVE_NETINET_TCP_H |
| 43 | #include <netinet/tcp.h> /* for TCP_NODELAY */ |
| 44 | #endif |
| 45 | |
| 46 | #include "mpm.h" |
| 47 | |
| 48 | #ifdef __cplusplus |
| 49 | extern "C" { |
| 50 | #endif |
| 51 | |
| 52 | /* The maximum length of the queue of pending connections, as defined |
| 53 | * by listen(2). Under some systems, it should be increased if you |
| 54 | * are experiencing a heavy TCP SYN flood attack. |
| 55 | * |
| 56 | * It defaults to 511 instead of 512 because some systems store it |
| 57 | * as an 8-bit datatype; 512 truncated to 8-bits is 0, while 511 is |
| 58 | * 255 when truncated. |
| 59 | */ |
| 60 | #ifndef DEFAULT_LISTENBACKLOG |
| 61 | #define DEFAULT_LISTENBACKLOG 511 |
| 62 | #endif |
| 63 | |
| 64 | /* Signal used to gracefully restart */ |
| 65 | #define AP_SIG_GRACEFUL SIGUSR1 |
| 66 | |
| 67 | /* Signal used to gracefully restart (without SIG prefix) */ |
| 68 | #define AP_SIG_GRACEFUL_SHORT USR1 |
| 69 | |
| 70 | /* Signal used to gracefully restart (as a quoted string) */ |
| 71 | #define AP_SIG_GRACEFUL_STRING "SIGUSR1" |
| 72 | |
| 73 | /* Signal used to gracefully stop */ |
| 74 | #define AP_SIG_GRACEFUL_STOP SIGWINCH |
| 75 | |
| 76 | /* Signal used to gracefully stop (without SIG prefix) */ |
| 77 | #define AP_SIG_GRACEFUL_STOP_SHORT WINCH |
| 78 | |
| 79 | /* Signal used to gracefully stop (as a quoted string) */ |
| 80 | #define AP_SIG_GRACEFUL_STOP_STRING "SIGWINCH" |
| 81 | |
| 82 | /** |
| 83 | * Make sure all child processes that have been spawned by the parent process |
| 84 | * have died. This includes process registered as "other_children". |
| 85 | * @warning This is only defined if the MPM defines |
| 86 | * AP_MPM_WANT_RECLAIM_CHILD_PROCESSES |
| 87 | * @param terminate Either 1 or 0. If 1, send the child processes SIGTERM |
| 88 | * each time through the loop. If 0, give the process time to die |
| 89 | * on its own before signalling it. |
| 90 | * @tip This function requires that some macros are defined by the MPM: <pre> |
| 91 | * MPM_CHILD_PID -- Get the pid from the specified spot in the scoreboard |
| 92 | * MPM_NOTE_CHILD_KILLED -- Note the child died in the scoreboard |
| 93 | * </pre> |
| 94 | * @tip The MPM child processes which are reclaimed are those listed |
| 95 | * in the scoreboard as well as those currently registered via |
| 96 | * ap_register_extra_mpm_process(). |
| 97 | */ |
| 98 | #ifdef AP_MPM_WANT_RECLAIM_CHILD_PROCESSES |
| 99 | void ap_reclaim_child_processes(int terminate); |
| 100 | #endif |
| 101 | |
| 102 | /** |
| 103 | * Catch any child processes that have been spawned by the parent process |
| 104 | * which have exited. This includes processes registered as "other_children". |
| 105 | * @warning This is only defined if the MPM defines |
| 106 | * AP_MPM_WANT_RECLAIM_CHILD_PROCESSES |
| 107 | * @tip This function requires that some macros are defined by the MPM: <pre> |
| 108 | * MPM_CHILD_PID -- Get the pid from the specified spot in the scoreboard |
| 109 | * MPM_NOTE_CHILD_KILLED -- Note the child died in the scoreboard |
| 110 | * </pre> |
| 111 | * @tip The MPM child processes which are relieved are those listed |
| 112 | * in the scoreboard as well as those currently registered via |
| 113 | * ap_register_extra_mpm_process(). |
| 114 | */ |
| 115 | #ifdef AP_MPM_WANT_RECLAIM_CHILD_PROCESSES |
| 116 | void ap_relieve_child_processes(void); |
| 117 | #endif |
| 118 | |
| 119 | /** |
| 120 | * Tell ap_reclaim_child_processes() and ap_relieve_child_processes() about |
| 121 | * an MPM child process which has no entry in the scoreboard. |
| 122 | * @warning This is only defined if the MPM defines |
| 123 | * AP_MPM_WANT_RECLAIM_CHILD_PROCESSES |
| 124 | * @param pid The process id of an MPM child process which should be |
| 125 | * reclaimed when ap_reclaim_child_processes() is called. |
| 126 | * @tip If an extra MPM child process terminates prior to calling |
| 127 | * ap_reclaim_child_processes(), remove it from the list of such processes |
| 128 | * by calling ap_unregister_extra_mpm_process(). |
| 129 | */ |
| 130 | #ifdef AP_MPM_WANT_RECLAIM_CHILD_PROCESSES |
| 131 | void ap_register_extra_mpm_process(pid_t pid); |
| 132 | #endif |
| 133 | |
| 134 | /** |
| 135 | * Unregister an MPM child process which was previously registered by a |
| 136 | * call to ap_register_extra_mpm_process(). |
| 137 | * @warning This is only defined if the MPM defines |
| 138 | * AP_MPM_WANT_RECLAIM_CHILD_PROCESSES |
| 139 | * @param pid The process id of an MPM child process which no longer needs to |
| 140 | * be reclaimed. |
| 141 | * @return 1 if the process was found and removed, 0 otherwise |
| 142 | */ |
| 143 | #ifdef AP_MPM_WANT_RECLAIM_CHILD_PROCESSES |
| 144 | int ap_unregister_extra_mpm_process(pid_t pid); |
| 145 | #endif |
| 146 | |
| 147 | /** |
| 148 | * Safely signal an MPM child process, if the process is in the |
| 149 | * current process group. Otherwise fail. |
| 150 | * @param pid the process id of a child process to signal |
| 151 | * @param sig the signal number to send |
| 152 | * @return APR_SUCCESS if signal is sent, otherwise an error as per kill(3); |
| 153 | * APR_EINVAL is returned if passed either an invalid (< 1) pid, or if |
| 154 | * the pid is not in the current process group |
| 155 | */ |
| 156 | #ifdef AP_MPM_WANT_RECLAIM_CHILD_PROCESSES |
| 157 | apr_status_t ap_mpm_safe_kill(pid_t pid, int sig); |
| 158 | #endif |
| 159 | |
| 160 | /** |
| 161 | * Determine if any child process has died. If no child process died, then |
| 162 | * this process sleeps for the amount of time specified by the MPM defined |
| 163 | * macro SCOREBOARD_MAINTENANCE_INTERVAL. |
| 164 | * @param status The return code if a process has died |
| 165 | * @param ret The process id of the process that died |
| 166 | * @param p The pool to allocate out of |
| 167 | */ |
| 168 | #ifdef AP_MPM_WANT_WAIT_OR_TIMEOUT |
| 169 | void ap_wait_or_timeout(apr_exit_why_e *status, int *exitcode, apr_proc_t *ret, |
| 170 | apr_pool_t *p); |
| 171 | #endif |
| 172 | |
| 173 | /** |
| 174 | * Log why a child died to the error log, if the child died without the |
| 175 | * parent signalling it. |
| 176 | * @param pid The child that has died |
| 177 | * @param status The status returned from ap_wait_or_timeout |
| 178 | * @return 0 on success, APEXIT_CHILDFATAL if MPM should terminate |
| 179 | */ |
| 180 | #ifdef AP_MPM_WANT_PROCESS_CHILD_STATUS |
| 181 | int ap_process_child_status(apr_proc_t *pid, apr_exit_why_e why, int status); |
| 182 | #endif |
| 183 | |
| 184 | #if defined(TCP_NODELAY) && !defined(MPE) && !defined(TPF) |
| 185 | /** |
| 186 | * Turn off the nagle algorithm for the specified socket. The nagle algorithm |
| 187 | * says that we should delay sending partial packets in the hopes of getting |
| 188 | * more data. There are bad interactions between persistent connections and |
| 189 | * Nagle's algorithm that have severe performance penalties. |
| 190 | * @param s The socket to disable nagle for. |
| 191 | */ |
| 192 | void ap_sock_disable_nagle(apr_socket_t *s); |
| 193 | #else |
| 194 | #define ap_sock_disable_nagle(s) /* NOOP */ |
| 195 | #endif |
| 196 | |
| 197 | #ifdef HAVE_GETPWNAM |
| 198 | /** |
| 199 | * Convert a username to a numeric ID |
| 200 | * @param name The name to convert |
| 201 | * @return The user id corresponding to a name |
| 202 | * @deffunc uid_t ap_uname2id(const char *name) |
| 203 | */ |
| 204 | AP_DECLARE(uid_t) ap_uname2id(const char *name); |
| 205 | #endif |
| 206 | |
| 207 | #ifdef HAVE_GETGRNAM |
| 208 | /** |
| 209 | * Convert a group name to a numeric ID |
| 210 | * @param name The name to convert |
| 211 | * @return The group id corresponding to a name |
| 212 | * @deffunc gid_t ap_gname2id(const char *name) |
| 213 | */ |
| 214 | AP_DECLARE(gid_t) ap_gname2id(const char *name); |
| 215 | #endif |
| 216 | |
| 217 | #define AP_MPM_HARD_LIMITS_FILE APACHE_MPM_DIR "/mpm_default.h" |
| 218 | |
| 219 | #ifndef HAVE_INITGROUPS |
| 220 | /** |
| 221 | * The initgroups() function initializes the group access list by reading the |
| 222 | * group database /etc/group and using all groups of which user is a member. |
| 223 | * The additional group basegid is also added to the list. |
| 224 | * @param name The user name - must be non-NULL |
| 225 | * @param basegid The basegid to add |
| 226 | * @return returns 0 on success |
| 227 | * @fn int initgroups(const char *name, gid_t basegid) |
| 228 | */ |
| 229 | int initgroups(const char *name, gid_t basegid); |
| 230 | #endif |
| 231 | |
| 232 | #ifdef AP_MPM_USES_POD |
| 233 | |
| 234 | typedef struct ap_pod_t ap_pod_t; |
| 235 | |
| 236 | struct ap_pod_t { |
| 237 | apr_file_t *pod_in; |
| 238 | apr_file_t *pod_out; |
| 239 | apr_pool_t *p; |
| 240 | }; |
| 241 | |
| 242 | /** |
| 243 | * Open the pipe-of-death. The pipe of death is used to tell all child |
| 244 | * processes that it is time to die gracefully. |
| 245 | * @param p The pool to use for allocating the pipe |
| 246 | */ |
| 247 | AP_DECLARE(apr_status_t) ap_mpm_pod_open(apr_pool_t *p, ap_pod_t **pod); |
| 248 | |
| 249 | /** |
| 250 | * Check the pipe to determine if the process has been signalled to die. |
| 251 | */ |
| 252 | AP_DECLARE(apr_status_t) ap_mpm_pod_check(ap_pod_t *pod); |
| 253 | |
| 254 | /** |
| 255 | * Close the pipe-of-death |
| 256 | */ |
| 257 | AP_DECLARE(apr_status_t) ap_mpm_pod_close(ap_pod_t *pod); |
| 258 | |
| 259 | /** |
| 260 | * Write data to the pipe-of-death, signalling that one child process |
| 261 | * should die. |
| 262 | * @param p The pool to use when allocating any required structures. |
| 263 | */ |
| 264 | AP_DECLARE(apr_status_t) ap_mpm_pod_signal(ap_pod_t *pod); |
| 265 | |
| 266 | /** |
| 267 | * Write data to the pipe-of-death, signalling that all child process |
| 268 | * should die. |
| 269 | * @param p The pool to use when allocating any required structures. |
| 270 | * @param num The number of child processes to kill |
| 271 | */ |
| 272 | AP_DECLARE(void) ap_mpm_pod_killpg(ap_pod_t *pod, int num); |
| 273 | #endif |
| 274 | |
| 275 | /* |
| 276 | * These data members are common to all mpms. Each new mpm |
| 277 | * should either use the appropriate ap_mpm_set_* function |
| 278 | * in their command table or create their own for custom or |
| 279 | * OS specific needs. These should work for most. |
| 280 | */ |
| 281 | |
| 282 | /** |
| 283 | * The maximum number of requests each child thread or |
| 284 | * process handles before dying off |
| 285 | */ |
| 286 | #ifdef AP_MPM_WANT_SET_MAX_REQUESTS |
| 287 | extern int ap_max_requests_per_child; |
| 288 | const char *ap_mpm_set_max_requests(cmd_parms *cmd, void *dummy, |
| 289 | const char *arg); |
| 290 | #endif |
| 291 | |
| 292 | /** |
| 293 | * The filename used to store the process id. |
| 294 | */ |
| 295 | #ifdef AP_MPM_WANT_SET_PIDFILE |
| 296 | extern const char *ap_pid_fname; |
| 297 | const char *ap_mpm_set_pidfile(cmd_parms *cmd, void *dummy, |
| 298 | const char *arg); |
| 299 | #endif |
| 300 | |
| 301 | /** |
| 302 | * The name of lockfile used when Apache needs to lock the accept() call. |
| 303 | */ |
| 304 | #ifdef AP_MPM_WANT_SET_LOCKFILE |
| 305 | extern const char *ap_lock_fname; |
| 306 | const char *ap_mpm_set_lockfile(cmd_parms *cmd, void *dummy, |
| 307 | const char *arg); |
| 308 | #endif |
| 309 | |
| 310 | /** |
| 311 | * The system mutex implementation to use for the accept mutex. |
| 312 | */ |
| 313 | #ifdef AP_MPM_WANT_SET_ACCEPT_LOCK_MECH |
| 314 | extern apr_lockmech_e ap_accept_lock_mech; |
| 315 | extern const char ap_valid_accept_mutex_string[]; |
| 316 | const char *ap_mpm_set_accept_lock_mech(cmd_parms *cmd, void *dummy, |
| 317 | const char *arg); |
| 318 | #endif |
| 319 | |
| 320 | /* |
| 321 | * Set the scorboard file. |
| 322 | */ |
| 323 | #ifdef AP_MPM_WANT_SET_SCOREBOARD |
| 324 | const char *ap_mpm_set_scoreboard(cmd_parms *cmd, void *dummy, |
| 325 | const char *arg); |
| 326 | #endif |
| 327 | |
| 328 | /* |
| 329 | * The directory that the server changes directory to dump core. |
| 330 | */ |
| 331 | #ifdef AP_MPM_WANT_SET_COREDUMPDIR |
| 332 | extern char ap_coredump_dir[MAX_STRING_LEN]; |
| 333 | extern int ap_coredumpdir_configured; |
| 334 | const char *ap_mpm_set_coredumpdir(cmd_parms *cmd, void *dummy, |
| 335 | const char *arg); |
| 336 | #endif |
| 337 | |
| 338 | /** |
| 339 | * Set the timeout period for a graceful shutdown. |
| 340 | */ |
| 341 | #ifdef AP_MPM_WANT_SET_GRACEFUL_SHUTDOWN |
| 342 | extern int ap_graceful_shutdown_timeout; |
| 343 | const char *ap_mpm_set_graceful_shutdown(cmd_parms *cmd, void *dummy, |
| 344 | const char *arg); |
| 345 | #define AP_GRACEFUL_SHUTDOWN_TIMEOUT_COMMAND \ |
| 346 | AP_INIT_TAKE1("GracefulShutdownTimeout", ap_mpm_set_graceful_shutdown : include/mpm_common.h line=343 column=13
ap_mpm_set_graceful_shutdown, NULL, \ |
| 347 | RSRC_CONF, "Maximum time in seconds to wait for child " \ |
| 348 | "processes to complete transactions during shutdown") |
| 349 | #endif |
| 350 | |
| 351 | |
| 352 | #ifdef AP_MPM_WANT_SIGNAL_SERVER |
| 353 | int ap_signal_server(int *, apr_pool_t *); |
| 354 | void ap_mpm_rewrite_args(process_rec *); |
| 355 | #endif |
| 356 | |
| 357 | #ifdef AP_MPM_WANT_SET_MAX_MEM_FREE |
| 358 | extern apr_uint32_t ap_max_mem_free; |
| 359 | extern const char *ap_mpm_set_max_mem_free(cmd_parms *cmd, void *dummy, |
| 360 | const char *arg); |
| 361 | #endif |
| 362 | |
| 363 | #ifdef AP_MPM_WANT_SET_STACKSIZE |
| 364 | extern apr_size_t ap_thread_stacksize; |
| 365 | extern const char *ap_mpm_set_thread_stacksize(cmd_parms *cmd, void *dummy, |
| 366 | const char *arg); |
| 367 | #endif |
| 368 | |
| 369 | #ifdef AP_MPM_WANT_FATAL_SIGNAL_HANDLER |
| 370 | extern apr_status_t ap_fatal_signal_setup(server_rec *s, apr_pool_t *pconf); |
| 371 | extern apr_status_t ap_fatal_signal_child_setup(server_rec *s); |
| 372 | #endif |
| 373 | |
| 374 | #if AP_ENABLE_EXCEPTION_HOOK |
| 375 | extern const char *ap_mpm_set_exception_hook(cmd_parms *cmd, void *dummy, |
| 376 | const char *arg); |
| 377 | #endif |
| 378 | |
| 379 | AP_DECLARE_HOOK(int,monitor,(apr_pool_t *p)) |
| 380 | |
| 381 | #ifdef __cplusplus |
| 382 | } |
| 383 | #endif |
| 384 | |
| 385 | #endif /* !APACHE_MPM_COMMON_H */ |
| 386 | /** @} */ |
| 387 | [EOF] |