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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 * This module is used to load Apache modules at runtime. This means that the
19 * server functionality can be extended without recompiling and even without
20 * taking the server down at all. Only a HUP or AP_SIG_GRACEFUL signal
21 * needs to be sent to the server to reload the dynamically loaded modules.
23 * To use, you'll first need to build your module as a shared library, then
24 * update your configuration (httpd.conf) to get the Apache core to load the
27 * The easiest way to build a module as a shared library is to use the
28 * `SharedModule' command in the Configuration file, instead of `AddModule'.
29 * You should also change the file extension from `.o' to `.so'. So, for
30 * example, to build the status module as a shared library edit Configuration
32 * AddModule modules/standard/mod_status.o
34 * SharedModule modules/standard/mod_status.so
36 * Run Configure and make. Now Apache's httpd binary will _not_ include
37 * mod_status. Instead a shared object called mod_status.so will be build, in
38 * the modules/standard directory. You can build most of the modules as shared
39 * libraries like this.
41 * To use the shared module, move the .so file(s) into an appropriate
42 * directory. You might like to create a directory called "modules" under you
43 * server root for this (e.g. /usr/local/httpd/modules).
45 * Then edit your conf/httpd.conf file, and add LoadModule lines. For
47 * LoadModule status_module modules/mod_status.so
49 * The first argument is the module's structure name (look at the end of the
50 * module source to find this). The second option is the path to the module
51 * file, relative to the server root. Put these directives right at the top
52 * of your httpd.conf file.
54 * Now you can start Apache. A message will be logged at "debug" level to your
55 * error_log to confirm that the module(s) are loaded (use "LogLevel debug"
56 * directive to get these log messages).
58 * If you edit the LoadModule directives while the server is live you can get
59 * Apache to re-load the modules by sending it a HUP or AP_SIG_GRACEFUL
60 * signal as normal. You can use this to dynamically change the capability
61 * of your server without bringing it down.
63 * Because currently there is only limited builtin support in the Configure
64 * script for creating the shared library files (`.so'), please consult your
65 * vendors cc(1), ld(1) and dlopen(3) manpages to find out the appropriate
66 * compiler and linker flags and insert them manually into the Configuration
67 * file under CFLAGS_SHLIB, LDFLAGS_SHLIB and LDFLAGS_SHLIB_EXPORT.
69 * If you still have problems figuring out the flags both try the paper
70 * http://developer.netscape.com/library/documentation/enterprise
71 * /unix/svrplug.htm#1013807
72 * or install a Perl 5 interpreter on your platform and then run the command
74 * $ perl -V:usedl -V:ccdlflags -V:cccdlflags -V:lddlflags
76 * This gives you what type of dynamic loading Perl 5 uses on your platform
77 * and which compiler and linker flags Perl 5 uses to create the shared object
80 * Another location where you can find useful hints is the `ltconfig' script
81 * of the GNU libtool 1.2 package. Search for your platform name inside the
82 * various "case" constructs.
88 #include "apr_strings.h"
89 #include "apr_errno.h"
92 #include "ap_config.h"
94 #include "http_config.h"
96 #include "ap_config.h"
98 module AP_MODULE_DECLARE_DATA so_module;
102 * Server configuration to keep track of actually
103 * loaded modules and the corresponding module name.
106 typedef struct moduleinfo {
111 typedef struct so_server_conf {
112 apr_array_header_t *loaded_modules;
115 static void *so_sconf_create(apr_pool_t *p, server_rec *s)
119 soc = (so_server_conf *)apr_pcalloc(p, sizeof(so_server_conf));
120 soc->loaded_modules = apr_array_make(p, DYNAMIC_MODULE_LIMIT,
129 * This is the cleanup for a loaded shared object. It unloads the module.
130 * This is called as a cleanup function from the core.
133 static apr_status_t unload_module(void *data)
135 moduleinfo *modi = (moduleinfo*)data;
137 /* only unload if module information is still existing */
138 if (modi->modp == NULL)
141 /* remove the module pointer from the core structure */
142 ap_remove_loaded_module(modi->modp);
144 /* destroy the module information */
151 * This is called for the directive LoadModule and actually loads
152 * a shared object file into the address space of the server process.
155 static const char *load_module(cmd_parms *cmd, void *dummy,
156 const char *modname, const char *filename)
158 apr_dso_handle_t *modhandle;
159 apr_dso_handle_sym_t modsym;
161 const char *szModuleFile = ap_server_root_relative(cmd->pool, filename);
162 so_server_conf *sconf;
167 /* we need to setup this value for dummy to make sure that we don't try
168 * to add a non-existant tree into the build when we return to
171 *(ap_directive_t **)dummy = NULL;
174 return apr_pstrcat(cmd->pool, "Invalid LoadModule path ",
179 * check for already existing module
180 * If it already exists, we have nothing to do
181 * Check both dynamically-loaded modules and statically-linked modules.
183 sconf = (so_server_conf *)ap_get_module_config(cmd->server->module_config,
185 modie = (moduleinfo *)sconf->loaded_modules->elts;
186 for (i = 0; i < sconf->loaded_modules->nelts; i++) {
188 if (modi->name != NULL && strcmp(modi->name, modname) == 0) {
189 ap_log_perror(APLOG_MARK, APLOG_WARNING, 0,
190 cmd->pool, "module %s is already loaded, skipping",
196 for (i = 0; ap_preloaded_modules[i]; i++) {
197 const char *preload_name;
198 apr_size_t preload_len;
199 apr_size_t thismod_len;
201 modp = ap_preloaded_modules[i];
203 /* make sure we're comparing apples with apples
204 * make sure name of preloaded module is mod_FOO.c
205 * make sure name of structure being loaded is FOO_module
208 if (memcmp(modp->name, "mod_", 4)) {
212 preload_name = modp->name + strlen("mod_");
213 preload_len = strlen(preload_name) - 2;
215 if (strlen(modname) <= strlen("_module")) {
218 thismod_len = strlen(modname) - strlen("_module");
219 if (strcmp(modname + thismod_len, "_module")) {
223 if (thismod_len != preload_len) {
227 if (!memcmp(modname, preload_name, preload_len)) {
228 return apr_pstrcat(cmd->pool, "module ", modname,
229 " is built-in and can't be loaded",
234 modi = apr_array_push(sconf->loaded_modules);
235 modi->name = modname;
238 * Load the file into the Apache address space
240 if (apr_dso_load(&modhandle, szModuleFile, cmd->pool) != APR_SUCCESS) {
243 return apr_pstrcat(cmd->pool, "Cannot load ", szModuleFile,
245 apr_dso_error(modhandle, my_error, sizeof(my_error)),
248 ap_log_perror(APLOG_MARK, APLOG_DEBUG, 0, cmd->pool,
249 "loaded module %s", modname);
252 * Retrieve the pointer to the module structure through the module name:
253 * First with the hidden variant (prefix `AP_') and then with the plain
256 if (apr_dso_sym(&modsym, modhandle, modname) != APR_SUCCESS) {
259 return apr_pstrcat(cmd->pool, "Can't locate API module structure `",
260 modname, "' in file ", szModuleFile, ": ",
261 apr_dso_error(modhandle, my_error, sizeof(my_error)),
264 modp = (module*) modsym;
265 modp->dynamic_load_handle = (apr_dso_handle_t *)modhandle;
269 * Make sure the found module structure is really a module structure
272 if (modp->magic != MODULE_MAGIC_COOKIE) {
273 return apr_psprintf(cmd->pool, "API module structure '%s' in file %s "
274 "is garbled - expected signature %08lx but saw "
275 "%08lx - perhaps this is not an Apache module DSO, "
276 "or was compiled for a different Apache version?",
277 modname, szModuleFile,
278 MODULE_MAGIC_COOKIE, modp->magic);
282 * Add this module to the Apache core structures
284 ap_add_loaded_module(modp, cmd->pool);
287 * Register a cleanup in the config apr_pool_t (normally pconf). When
288 * we do a restart (or shutdown) this cleanup will cause the
289 * shared object to be unloaded.
291 apr_pool_cleanup_register(cmd->pool, modi, unload_module, apr_pool_cleanup_null);
294 * Finally we need to run the configuration process for the module
296 ap_single_module_configure(cmd->pool, cmd->server, modp);
302 * This implements the LoadFile directive and loads an arbitrary
303 * shared object file into the adress space of the server process.
306 static const char *load_file(cmd_parms *cmd, void *dummy, const char *filename)
308 apr_dso_handle_t *handle;
311 file = ap_server_root_relative(cmd->pool, filename);
314 return apr_pstrcat(cmd->pool, "Invalid LoadFile path ",
318 if (apr_dso_load(&handle, file, cmd->pool) != APR_SUCCESS) {
321 return apr_pstrcat(cmd->pool, "Cannot load ", filename,
323 apr_dso_error(handle, my_error, sizeof(my_error)),
327 ap_log_error(APLOG_MARK, APLOG_DEBUG, 0, NULL,
328 "loaded file %s", filename);
333 #else /* not NO_DLOPEN */
335 static const char *load_file(cmd_parms *cmd, void *dummy, const char *filename)
337 ap_log_perror(APLOG_MARK, APLOG_STARTUP, 0, cmd->pool,
338 "WARNING: LoadFile not supported on this platform");
342 static const char *load_module(cmd_parms *cmd, void *dummy,
343 const char *modname, const char *filename)
345 ap_log_perror(APLOG_MARK, APLOG_STARTUP, 0, cmd->pool,
346 "WARNING: LoadModule not supported on this platform");
350 #endif /* NO_DLOPEN */
352 static const command_rec so_cmds[] = {
353 AP_INIT_TAKE2("LoadModule", load_module, NULL, RSRC_CONF | EXEC_ON_READ,
354 "a module name and the name of a shared object file to load it from"),
355 AP_INIT_ITERATE("LoadFile", load_file, NULL, RSRC_CONF | EXEC_ON_READ,
356 "shared object file or library to load into the server at runtime"),
360 module AP_MODULE_DECLARE_DATA so_module = {
361 STANDARD20_MODULE_STUFF,
362 NULL, /* create per-dir config */
363 NULL, /* merge per-dir config */
364 so_sconf_create, /* server config */
365 NULL, /* merge server config */
366 so_cmds, /* command apr_table_t */
367 NULL /* register hooks */