granicus.if.org Git - apache/blob - include/mpm_common.h

   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 #include "ap_mpm.h"
  42
  43 #if APR_HAVE_NETINET_TCP_H
  44 #include <netinet/tcp.h>    /* for TCP_NODELAY */
  45 #endif
  46
  47 #include "apr_proc_mutex.h"
  48
  49 #ifdef __cplusplus
  50 extern "C" {
  51 #endif
  52
  53 /* The maximum length of the queue of pending connections, as defined
  54  * by listen(2).  Under some systems, it should be increased if you
  55  * are experiencing a heavy TCP SYN flood attack.
  56  *
  57  * It defaults to 511 instead of 512 because some systems store it
  58  * as an 8-bit datatype; 512 truncated to 8-bits is 0, while 511 is
  59  * 255 when truncated.
  60  */
  61 #ifndef DEFAULT_LISTENBACKLOG
  62 #define DEFAULT_LISTENBACKLOG 511
  63 #endif
  64
  65 /* Signal used to gracefully restart */
  66 #define AP_SIG_GRACEFUL SIGUSR1
  67
  68 /* Signal used to gracefully restart (without SIG prefix) */
  69 #define AP_SIG_GRACEFUL_SHORT USR1
  70
  71 /* Signal used to gracefully restart (as a quoted string) */
  72 #define AP_SIG_GRACEFUL_STRING "SIGUSR1"
  73
  74 /* Signal used to gracefully stop */
  75 #define AP_SIG_GRACEFUL_STOP SIGWINCH
  76
  77 /* Signal used to gracefully stop (without SIG prefix) */
  78 #define AP_SIG_GRACEFUL_STOP_SHORT WINCH
  79
  80 /* Signal used to gracefully stop (as a quoted string) */
  81 #define AP_SIG_GRACEFUL_STOP_STRING "SIGWINCH"
  82
  83 /**
  84  * Make sure all child processes that have been spawned by the parent process
  85  * have died.  This includes process registered as "other_children".
  86  * @param terminate Either 1 or 0.  If 1, send the child processes SIGTERM
  87  *        each time through the loop.  If 0, give the process time to die
  88  *        on its own before signalling it.
  89  * @note This function requires that a hook is implemented by the MPM: <pre>
  90  *  mpm_note_child_killed -- Note the child died in the scoreboard
  91  * </pre>
  92  *
  93  * @note The MPM child processes which are reclaimed are those listed
  94  * in the scoreboard as well as those currently registered via
  95  * ap_register_extra_mpm_process().
  96  */
  97 void ap_reclaim_child_processes(int terminate);
  98
  99 /**
 100  * Catch any child processes that have been spawned by the parent process
 101  * which have exited. This includes processes registered as "other_children".
 102  *
 103  * @note This function requires that a hook is implemented by the MPM: <pre>
 104  *  mpm_note_child_killed -- Note the child died in the scoreboard
 105  * </pre>
 106  *
 107  * @note The MPM child processes which are relieved are those listed
 108  * in the scoreboard as well as those currently registered via
 109  * ap_register_extra_mpm_process().
 110  */
 111 void ap_relieve_child_processes(void);
 112
 113 /**
 114  * Tell ap_reclaim_child_processes() and ap_relieve_child_processes() about
 115  * an MPM child process which has no entry in the scoreboard.
 116  * @param pid The process id of an MPM child process which should be
 117  * reclaimed when ap_reclaim_child_processes() is called.
 118  *
 119  * @note If an extra MPM child process terminates prior to calling
 120  * ap_reclaim_child_processes(), remove it from the list of such processes
 121  * by calling ap_unregister_extra_mpm_process().
 122  */
 123 void ap_register_extra_mpm_process(pid_t pid);
 124
 125 /**
 126  * Unregister an MPM child process which was previously registered by a
 127  * call to ap_register_extra_mpm_process().
 128  * @param pid The process id of an MPM child process which no longer needs to
 129  * be reclaimed.
 130  * @return 1 if the process was found and removed, 0 otherwise
 131  */
 132 int ap_unregister_extra_mpm_process(pid_t pid);
 133
 134 /**
 135  * Safely signal an MPM child process, if the process is in the
 136  * current process group.  Otherwise fail.
 137  * @param pid the process id of a child process to signal
 138  * @param sig the signal number to send
 139  * @return APR_SUCCESS if signal is sent, otherwise an error as per kill(3);
 140  * APR_EINVAL is returned if passed either an invalid (< 1) pid, or if
 141  * the pid is not in the current process group
 142  */
 143 apr_status_t ap_mpm_safe_kill(pid_t pid, int sig);
 144
 145 /**
 146  * Determine if any child process has died.  If no child process died, then
 147  * this process sleeps for the amount of time specified by the MPM defined
 148  * macro SCOREBOARD_MAINTENANCE_INTERVAL.
 149  * @param status The return code if a process has died
 150  * @param exitcode The returned exit status of the child, if a child process
 151  *                 dies, or the signal that caused the child to die.
 152  * @param ret The process id of the process that died
 153  * @param p The pool to allocate out of
 154  * @param s The server_rec to pass
 155  */
 156 void ap_wait_or_timeout(apr_exit_why_e *status, int *exitcode, apr_proc_t *ret,
 157                         apr_pool_t *p, server_rec *s);
 158
 159 /**
 160  * Log why a child died to the error log, if the child died without the
 161  * parent signalling it.
 162  * @param pid The child that has died
 163  * @param why The return code of the child process
 164  * @param status The status returned from ap_wait_or_timeout
 165  * @return 0 on success, APEXIT_CHILDFATAL if MPM should terminate
 166  */
 167 int ap_process_child_status(apr_proc_t *pid, apr_exit_why_e why, int status);
 168
 169 #if defined(TCP_NODELAY)
 170 /**
 171  * Turn off the nagle algorithm for the specified socket.  The nagle algorithm
 172  * says that we should delay sending partial packets in the hopes of getting
 173  * more data.  There are bad interactions between persistent connections and
 174  * Nagle's algorithm that have severe performance penalties.
 175  * @param s The socket to disable nagle for.
 176  */
 177 void ap_sock_disable_nagle(apr_socket_t *s);
 178 #else
 179 #define ap_sock_disable_nagle(s)        /* NOOP */
 180 #endif
 181
 182 #ifdef HAVE_GETPWNAM
 183 /**
 184  * Convert a username to a numeric ID
 185  * @param name The name to convert
 186  * @return The user id corresponding to a name
 187  * @fn uid_t ap_uname2id(const char *name)
 188  */
 189 AP_DECLARE(uid_t) ap_uname2id(const char *name);
 190 #endif
 191
 192 #ifdef HAVE_GETGRNAM
 193 /**
 194  * Convert a group name to a numeric ID
 195  * @param name The name to convert
 196  * @return The group id corresponding to a name
 197  * @fn gid_t ap_gname2id(const char *name)
 198  */
 199 AP_DECLARE(gid_t) ap_gname2id(const char *name);
 200 #endif
 201
 202 typedef struct ap_pod_t ap_pod_t;
 203
 204 struct ap_pod_t {
 205     apr_file_t *pod_in;
 206     apr_file_t *pod_out;
 207     apr_pool_t *p;
 208 };
 209
 210 /**
 211  * Open the pipe-of-death.  The pipe of death is used to tell all child
 212  * processes that it is time to die gracefully.
 213  * @param p The pool to use for allocating the pipe
 214  * @param pod the pipe-of-death that is created.
 215  */
 216 AP_DECLARE(apr_status_t) ap_mpm_pod_open(apr_pool_t *p, ap_pod_t **pod);
 217
 218 /**
 219  * Check the pipe to determine if the process has been signalled to die.
 220  */
 221 AP_DECLARE(apr_status_t) ap_mpm_pod_check(ap_pod_t *pod);
 222
 223 /**
 224  * Close the pipe-of-death
 225  *
 226  * @param pod the pipe-of-death to close.
 227  */
 228 AP_DECLARE(apr_status_t) ap_mpm_pod_close(ap_pod_t *pod);
 229
 230 /**
 231  * Write data to the pipe-of-death, signalling that one child process
 232  * should die.
 233  * @param pod the pipe-of-death to write to.
 234  */
 235 AP_DECLARE(apr_status_t) ap_mpm_pod_signal(ap_pod_t *pod);
 236
 237 /**
 238  * Write data to the pipe-of-death, signalling that all child process
 239  * should die.
 240  * @param pod The pipe-of-death to write to.
 241  * @param num The number of child processes to kill
 242  */
 243 AP_DECLARE(void) ap_mpm_pod_killpg(ap_pod_t *pod, int num);
 244
 245 /**
 246  * Check that exactly one MPM is loaded
 247  * Returns NULL if yes, error string if not.
 248  */
 249 AP_DECLARE(const char *) ap_check_mpm(void);
 250
 251 /*
 252  * These data members are common to all mpms. Each new mpm
 253  * should either use the appropriate ap_mpm_set_* function
 254  * in their command table or create their own for custom or
 255  * OS specific needs. These should work for most.
 256  */
 257
 258 /**
 259  * The maximum number of requests each child thread or
 260  * process handles before dying off
 261  */
 262 extern int ap_max_requests_per_child;
 263 const char *ap_mpm_set_max_requests(cmd_parms *cmd, void *dummy,
 264                                     const char *arg);
 265
 266 /**
 267  * The filename used to store the process id.
 268  */
 269 extern const char *ap_pid_fname;
 270 const char *ap_mpm_set_pidfile(cmd_parms *cmd, void *dummy,
 271                                const char *arg);
 272
 273 /*
 274  * The directory that the server changes directory to dump core.
 275  */
 276 extern char ap_coredump_dir[MAX_STRING_LEN];
 277 extern int ap_coredumpdir_configured;
 278 const char *ap_mpm_set_coredumpdir(cmd_parms *cmd, void *dummy,
 279                                    const char *arg);
 280
 281 /**
 282  * Set the timeout period for a graceful shutdown.
 283  */
 284 extern int ap_graceful_shutdown_timeout;
 285 const char *ap_mpm_set_graceful_shutdown(cmd_parms *cmd, void *dummy,
 286                                          const char *arg);
 287 #define AP_GRACEFUL_SHUTDOWN_TIMEOUT_COMMAND \
 288 AP_INIT_TAKE1("GracefulShutdownTimeout", ap_mpm_set_graceful_shutdown, NULL, \
 289               RSRC_CONF, "Maximum time in seconds to wait for child "        \
 290               "processes to complete transactions during shutdown")
 291
 292
 293 int ap_signal_server(int *, apr_pool_t *);
 294 void ap_mpm_rewrite_args(process_rec *);
 295
 296 extern apr_uint32_t ap_max_mem_free;
 297 extern const char *ap_mpm_set_max_mem_free(cmd_parms *cmd, void *dummy,
 298                                            const char *arg);
 299
 300 extern apr_size_t ap_thread_stacksize;
 301 extern const char *ap_mpm_set_thread_stacksize(cmd_parms *cmd, void *dummy,
 302                                                const char *arg);
 303
 304 extern apr_status_t ap_fatal_signal_setup(server_rec *s, apr_pool_t *pconf);
 305 extern apr_status_t ap_fatal_signal_child_setup(server_rec *s);
 306
 307 #if AP_ENABLE_EXCEPTION_HOOK
 308 extern const char *ap_mpm_set_exception_hook(cmd_parms *cmd, void *dummy,
 309                                              const char *arg);
 310 #endif
 311
 312 AP_DECLARE(apr_status_t) ap_mpm_note_child_killed(int childnum);
 313
 314 AP_DECLARE_HOOK(int,monitor,(apr_pool_t *p, server_rec *s))
 315
 316 /* register modules that undertake to manage system security */
 317 AP_DECLARE(int) ap_sys_privileges_handlers(int inc);
 318 AP_DECLARE_HOOK(int, drop_privileges, (apr_pool_t * pchild, server_rec * s))
 319
 320 /* implement the ap_mpm_query() function
 321  * The MPM should return OK+APR_ENOTIMPL for any unimplemented query codes;
 322  * modules which intercede for specific query codes should DECLINE for others.
 323  */
 324 AP_DECLARE_HOOK(int, mpm_query, (int query_code, int *result, apr_status_t *rv))
 325
 326 /* child specified by index has been killed */
 327 AP_DECLARE_HOOK(apr_status_t, mpm_note_child_killed, (int childnum))
 328
 329 /* register the specified callback */
 330 AP_DECLARE_HOOK(apr_status_t, mpm_register_timed_callback,
 331                 (apr_time_t t, ap_mpm_callback_fn_t *cbfn, void *baton))
 332
 333 /* get MPM name (e.g., "prefork" or "event") */
 334 AP_DECLARE_HOOK(const char *,mpm_get_name,(void))
 335
 336 /* mutex type string for accept mutex, if any; MPMs should use the
 337  * same mutex type for ease of configuration
 338  */
 339 #define AP_ACCEPT_MUTEX_TYPE "mpm-accept"
 340
 341 #ifdef __cplusplus
 342 }
 343 #endif
 344
 345 #endif /* !APACHE_MPM_COMMON_H */
 346 /** @} */