modules/core/mod_so.c

	mod_so.c revision b2c17021012bc4f7cd8e374c6bd72b926737320f
b66914021bd429f41311d2909a7e9289866da7fdnd/* Licensed to the Apache Software Foundation (ASF) under one or more
b51bf223f42d43ca6b1b33c95124edcfa5a871a4nd * contributor license agreements.  See the NOTICE file distributed with
9963f91528694fb21e93da8584c31f226c6de97akess * this work for additional information regarding copyright ownership.
b66914021bd429f41311d2909a7e9289866da7fdnd * The ASF licenses this file to You under the Apache License, Version 2.0
b66914021bd429f41311d2909a7e9289866da7fdnd * (the "License"); you may not use this file except in compliance with
031b91a62d25106ae69d4693475c79618dd5e884fielding * the License.  You may obtain a copy of the License at
031b91a62d25106ae69d4693475c79618dd5e884fielding *
031b91a62d25106ae69d4693475c79618dd5e884fielding *     http://www.apache.org/licenses/LICENSE-2.0
031b91a62d25106ae69d4693475c79618dd5e884fielding *
031b91a62d25106ae69d4693475c79618dd5e884fielding * Unless required by applicable law or agreed to in writing, software
031b91a62d25106ae69d4693475c79618dd5e884fielding * distributed under the License is distributed on an "AS IS" BASIS,
b66914021bd429f41311d2909a7e9289866da7fdnd * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
b66914021bd429f41311d2909a7e9289866da7fdnd * See the License for the specific language governing permissions and
b66914021bd429f41311d2909a7e9289866da7fdnd * limitations under the License.
b66914021bd429f41311d2909a7e9289866da7fdnd */
b66914021bd429f41311d2909a7e9289866da7fdnd
b66914021bd429f41311d2909a7e9289866da7fdnd/*
b66914021bd429f41311d2909a7e9289866da7fdnd * This module is used to load Apache modules at runtime. This means that the
b66914021bd429f41311d2909a7e9289866da7fdnd * server functionality can be extended without recompiling and even without
b66914021bd429f41311d2909a7e9289866da7fdnd * taking the server down at all. Only a HUP or AP_SIG_GRACEFUL signal
b66914021bd429f41311d2909a7e9289866da7fdnd * needs to be sent to the server to reload the dynamically loaded modules.
eed2a23d9b5986937f1e2b1c120be97744508a72nd *
eed2a23d9b5986937f1e2b1c120be97744508a72nd * To use, you'll first need to build your module as a shared library, then
eed2a23d9b5986937f1e2b1c120be97744508a72nd * update your configuration (httpd.conf) to get the Apache core to load the
eed2a23d9b5986937f1e2b1c120be97744508a72nd * module at start-up.
eed2a23d9b5986937f1e2b1c120be97744508a72nd *
eed2a23d9b5986937f1e2b1c120be97744508a72nd * The easiest way to build a module as a shared library is to use the
eed2a23d9b5986937f1e2b1c120be97744508a72nd * `SharedModule' command in the Configuration file, instead of `AddModule'.
eed2a23d9b5986937f1e2b1c120be97744508a72nd * You should also change the file extension from `.o' to `.so'. So, for
eed2a23d9b5986937f1e2b1c120be97744508a72nd * example, to build the status module as a shared library edit Configuration
eed2a23d9b5986937f1e2b1c120be97744508a72nd * and change
eed2a23d9b5986937f1e2b1c120be97744508a72nd *   AddModule    modules/standard/mod_status.o
eed2a23d9b5986937f1e2b1c120be97744508a72nd * to
eed2a23d9b5986937f1e2b1c120be97744508a72nd *   SharedModule modules/standard/mod_status.so
eed2a23d9b5986937f1e2b1c120be97744508a72nd *
eed2a23d9b5986937f1e2b1c120be97744508a72nd * Run Configure and make. Now Apache's httpd binary will _not_ include
eed2a23d9b5986937f1e2b1c120be97744508a72nd * mod_status. Instead a shared object called mod_status.so will be build, in
eed2a23d9b5986937f1e2b1c120be97744508a72nd * the modules/standard directory. You can build most of the modules as shared
eed2a23d9b5986937f1e2b1c120be97744508a72nd * libraries like this.
eed2a23d9b5986937f1e2b1c120be97744508a72nd *
eed2a23d9b5986937f1e2b1c120be97744508a72nd * To use the shared module, move the .so file(s) into an appropriate
eed2a23d9b5986937f1e2b1c120be97744508a72nd * directory. You might like to create a directory called "modules" under you
eed2a23d9b5986937f1e2b1c120be97744508a72nd * server root for this (e.g. /usr/local/httpd/modules).
eed2a23d9b5986937f1e2b1c120be97744508a72nd *
eed2a23d9b5986937f1e2b1c120be97744508a72nd * Then edit your conf/httpd.conf file, and add LoadModule lines. For
eed2a23d9b5986937f1e2b1c120be97744508a72nd * example
eed2a23d9b5986937f1e2b1c120be97744508a72nd *   LoadModule  status_module   modules/mod_status.so
eed2a23d9b5986937f1e2b1c120be97744508a72nd *
eed2a23d9b5986937f1e2b1c120be97744508a72nd * The first argument is the module's structure name (look at the end of the
eed2a23d9b5986937f1e2b1c120be97744508a72nd * module source to find this). The second option is the path to the module
eed2a23d9b5986937f1e2b1c120be97744508a72nd * file, relative to the server root.  Put these directives right at the top
eed2a23d9b5986937f1e2b1c120be97744508a72nd * of your httpd.conf file.
eed2a23d9b5986937f1e2b1c120be97744508a72nd *
eed2a23d9b5986937f1e2b1c120be97744508a72nd * Now you can start Apache. A message will be logged at "debug" level to your
eed2a23d9b5986937f1e2b1c120be97744508a72nd * error_log to confirm that the module(s) are loaded (use "LogLevel debug"
eed2a23d9b5986937f1e2b1c120be97744508a72nd * directive to get these log messages).
eed2a23d9b5986937f1e2b1c120be97744508a72nd *
eed2a23d9b5986937f1e2b1c120be97744508a72nd * If you edit the LoadModule directives while the server is live you can get
eed2a23d9b5986937f1e2b1c120be97744508a72nd * Apache to re-load the modules by sending it a HUP or AP_SIG_GRACEFUL
eed2a23d9b5986937f1e2b1c120be97744508a72nd * signal as normal.  You can use this to dynamically change the capability
eed2a23d9b5986937f1e2b1c120be97744508a72nd * of your server without bringing it down.
eed2a23d9b5986937f1e2b1c120be97744508a72nd *
eed2a23d9b5986937f1e2b1c120be97744508a72nd * Because currently there is only limited builtin support in the Configure
eed2a23d9b5986937f1e2b1c120be97744508a72nd * script for creating the shared library files (`.so'), please consult your
eed2a23d9b5986937f1e2b1c120be97744508a72nd * vendors cc(1), ld(1) and dlopen(3) manpages to find out the appropriate
eed2a23d9b5986937f1e2b1c120be97744508a72nd * compiler and linker flags and insert them manually into the Configuration
eed2a23d9b5986937f1e2b1c120be97744508a72nd * file under CFLAGS_SHLIB, LDFLAGS_SHLIB and LDFLAGS_SHLIB_EXPORT.
eed2a23d9b5986937f1e2b1c120be97744508a72nd *
eed2a23d9b5986937f1e2b1c120be97744508a72nd * If you still have problems figuring out the flags both try the paper
eed2a23d9b5986937f1e2b1c120be97744508a72nd *     http://developer.netscape.com/library/documentation/enterprise
eed2a23d9b5986937f1e2b1c120be97744508a72nd *                                          /unix/svrplug.htm#1013807
eed2a23d9b5986937f1e2b1c120be97744508a72nd * or install a Perl 5 interpreter on your platform and then run the command
bcf004854091600aa279525d6772e1827114d39dnd *
eed2a23d9b5986937f1e2b1c120be97744508a72nd *     $ perl -V:usedl -V:ccdlflags -V:cccdlflags -V:lddlflags
eed2a23d9b5986937f1e2b1c120be97744508a72nd *
eed2a23d9b5986937f1e2b1c120be97744508a72nd * This gives you what type of dynamic loading Perl 5 uses on your platform
4930be147adf9e3f6d3ca9313a6524f9bf654b2dnd * and which compiler and linker flags Perl 5 uses to create the shared object
4930be147adf9e3f6d3ca9313a6524f9bf654b2dnd * files.
4930be147adf9e3f6d3ca9313a6524f9bf654b2dnd *
4930be147adf9e3f6d3ca9313a6524f9bf654b2dnd * Another location where you can find useful hints is the `ltconfig' script
4930be147adf9e3f6d3ca9313a6524f9bf654b2dnd * of the GNU libtool 1.2 package. Search for your platform name inside the
4930be147adf9e3f6d3ca9313a6524f9bf654b2dnd * various "case" constructs.
4930be147adf9e3f6d3ca9313a6524f9bf654b2dnd *
4930be147adf9e3f6d3ca9313a6524f9bf654b2dnd */
eed2a23d9b5986937f1e2b1c120be97744508a72nd
4930be147adf9e3f6d3ca9313a6524f9bf654b2dnd#include "apr.h"
4930be147adf9e3f6d3ca9313a6524f9bf654b2dnd#include "apr_dso.h"
4930be147adf9e3f6d3ca9313a6524f9bf654b2dnd#include "apr_strings.h"
4930be147adf9e3f6d3ca9313a6524f9bf654b2dnd#include "apr_errno.h"
eed2a23d9b5986937f1e2b1c120be97744508a72nd
eed2a23d9b5986937f1e2b1c120be97744508a72nd#include "ap_config.h"
eed2a23d9b5986937f1e2b1c120be97744508a72nd#include "httpd.h"
eed2a23d9b5986937f1e2b1c120be97744508a72nd#include "http_config.h"
eed2a23d9b5986937f1e2b1c120be97744508a72nd#include "http_log.h"
eed2a23d9b5986937f1e2b1c120be97744508a72nd#include "http_core.h"
eed2a23d9b5986937f1e2b1c120be97744508a72nd
eed2a23d9b5986937f1e2b1c120be97744508a72nd#include "mod_so.h"
eed2a23d9b5986937f1e2b1c120be97744508a72nd
eed2a23d9b5986937f1e2b1c120be97744508a72ndmodule AP_MODULE_DECLARE_DATA so_module;
eed2a23d9b5986937f1e2b1c120be97744508a72nd
eed2a23d9b5986937f1e2b1c120be97744508a72nd
eed2a23d9b5986937f1e2b1c120be97744508a72nd/*
eed2a23d9b5986937f1e2b1c120be97744508a72nd * Server configuration to keep track of actually
9963f91528694fb21e93da8584c31f226c6de97akess * loaded modules and the corresponding module name.
bcf004854091600aa279525d6772e1827114d39dnd */
9963f91528694fb21e93da8584c31f226c6de97akess
eed2a23d9b5986937f1e2b1c120be97744508a72ndtypedef struct so_server_conf {
eed2a23d9b5986937f1e2b1c120be97744508a72nd    apr_array_header_t *loaded_modules;
b51bf223f42d43ca6b1b33c95124edcfa5a871a4nd} so_server_conf;
b51bf223f42d43ca6b1b33c95124edcfa5a871a4nd
eed2a23d9b5986937f1e2b1c120be97744508a72ndstatic void *so_sconf_create(apr_pool_t *p, server_rec *s)
eed2a23d9b5986937f1e2b1c120be97744508a72nd{
eed2a23d9b5986937f1e2b1c120be97744508a72nd    so_server_conf *soc;
eed2a23d9b5986937f1e2b1c120be97744508a72nd
eed2a23d9b5986937f1e2b1c120be97744508a72nd    soc = (so_server_conf *)apr_pcalloc(p, sizeof(so_server_conf));
eed2a23d9b5986937f1e2b1c120be97744508a72nd    soc->loaded_modules = apr_array_make(p, DYNAMIC_MODULE_LIMIT,
eed2a23d9b5986937f1e2b1c120be97744508a72nd                                     sizeof(ap_module_symbol_t));
eed2a23d9b5986937f1e2b1c120be97744508a72nd
eed2a23d9b5986937f1e2b1c120be97744508a72nd    return (void *)soc;
b51bf223f42d43ca6b1b33c95124edcfa5a871a4nd}
eed2a23d9b5986937f1e2b1c120be97744508a72nd
eed2a23d9b5986937f1e2b1c120be97744508a72nd#ifndef NO_DLOPEN
eed2a23d9b5986937f1e2b1c120be97744508a72nd
eed2a23d9b5986937f1e2b1c120be97744508a72nd/*
eed2a23d9b5986937f1e2b1c120be97744508a72nd * This is the cleanup for a loaded shared object. It unloads the module.
eed2a23d9b5986937f1e2b1c120be97744508a72nd * This is called as a cleanup function from the core.
eed2a23d9b5986937f1e2b1c120be97744508a72nd */
eed2a23d9b5986937f1e2b1c120be97744508a72nd
4930be147adf9e3f6d3ca9313a6524f9bf654b2dndstatic apr_status_t unload_module(void *data)
4930be147adf9e3f6d3ca9313a6524f9bf654b2dnd{
eed2a23d9b5986937f1e2b1c120be97744508a72nd    ap_module_symbol_t *modi = (ap_module_symbol_t*)data;
eed2a23d9b5986937f1e2b1c120be97744508a72nd
eed2a23d9b5986937f1e2b1c120be97744508a72nd    /* only unload if module information is still existing */
eed2a23d9b5986937f1e2b1c120be97744508a72nd    if (modi->modp == NULL)
eed2a23d9b5986937f1e2b1c120be97744508a72nd        return APR_SUCCESS;
eed2a23d9b5986937f1e2b1c120be97744508a72nd
eed2a23d9b5986937f1e2b1c120be97744508a72nd    /* remove the module pointer from the core structure */
eed2a23d9b5986937f1e2b1c120be97744508a72nd    ap_remove_loaded_module(modi->modp);
eed2a23d9b5986937f1e2b1c120be97744508a72nd
    /* destroy the module information */
    modi->modp = NULL;
    modi->name = NULL;
    return APR_SUCCESS;
}

static const char *dso_load(cmd_parms *cmd, apr_dso_handle_t **modhandlep,
                            const char *filename, const char **used_filename)
{
    int retry = 0;
    const char *fullname = ap_server_root_relative(cmd->temp_pool, filename);
    char my_error[256];
    if (filename != NULL && ap_strchr_c(filename, '/') == NULL) {
        /* retry on error without path to use dlopen()'s search path */
        retry = 1;
    }

    if (fullname == NULL && !retry) {
        return apr_psprintf(cmd->temp_pool, "Invalid %s path %s",
                            cmd->cmd->name, filename);
    }
    *used_filename = fullname;
    if (apr_dso_load(modhandlep, fullname, cmd->pool) == APR_SUCCESS) {
        return NULL;
    }
    if (retry) {
        *used_filename = filename;
        if (apr_dso_load(modhandlep, filename, cmd->pool) == APR_SUCCESS)
            return NULL;
    }

    return apr_pstrcat(cmd->temp_pool, "Cannot load ", filename,
                        " into server: ",
                        apr_dso_error(*modhandlep, my_error, sizeof(my_error)),
                        NULL);
}

/*
 * This is called for the directive LoadModule and actually loads
 * a shared object file into the address space of the server process.
 */

static const char *load_module(cmd_parms *cmd, void *dummy,
                               const char *modname, const char *filename)
{
    apr_dso_handle_t *modhandle;
    apr_dso_handle_sym_t modsym;
    module *modp;
    const char *module_file;
    so_server_conf *sconf;
    ap_module_symbol_t *modi;
    ap_module_symbol_t *modie;
    int i;
    const char *error;

    /* we need to setup this value for dummy to make sure that we don't try
     * to add a non-existant tree into the build when we return to
     * execute_now.
     */
    *(ap_directive_t **)dummy = NULL;

    /*
     * check for already existing module
     * If it already exists, we have nothing to do
     * Check both dynamically-loaded modules and statically-linked modules.
     */
    sconf = (so_server_conf *)ap_get_module_config(cmd->server->module_config,
                                                &so_module);
    modie = (ap_module_symbol_t *)sconf->loaded_modules->elts;
    for (i = 0; i < sconf->loaded_modules->nelts; i++) {
        modi = &modie[i];
        if (modi->name != NULL && strcmp(modi->name, modname) == 0) {
            ap_log_perror(APLOG_MARK, APLOG_WARNING, 0, cmd->pool, APLOGNO(01574)
                          "module %s is already loaded, skipping",
                          modname);
            return NULL;
        }
    }

    for (i = 0; ap_preloaded_modules[i]; i++) {
        const char *preload_name;
        apr_size_t preload_len;
        apr_size_t thismod_len;

        modp = ap_preloaded_modules[i];

        /* make sure we're comparing apples with apples
         * make sure name of preloaded module is mod_FOO.c
         * make sure name of structure being loaded is FOO_module
         */

        if (memcmp(modp->name, "mod_", 4)) {
            continue;
        }

        preload_name = modp->name + strlen("mod_");
        preload_len = strlen(preload_name) - 2;

        if (strlen(modname) <= strlen("_module")) {
            continue;
        }
        thismod_len = strlen(modname) - strlen("_module");
        if (strcmp(modname + thismod_len, "_module")) {
            continue;
        }

        if (thismod_len != preload_len) {
            continue;
        }

        if (!memcmp(modname, preload_name, preload_len)) {
            return apr_pstrcat(cmd->pool, "module ", modname,
                               " is built-in and can't be loaded",
                               NULL);
        }
    }

    modi = apr_array_push(sconf->loaded_modules);
    modi->name = modname;

    /*
     * Load the file into the Apache address space
     */
    error = dso_load(cmd, &modhandle, filename, &module_file);
    if (error)
        return error;
    ap_log_perror(APLOG_MARK, APLOG_DEBUG, 0, cmd->pool, APLOGNO(01575)
                 "loaded module %s from %s", modname, module_file);

    /*
     * Retrieve the pointer to the module structure through the module name:
     * First with the hidden variant (prefix `AP_') and then with the plain
     * symbol name.
     */
    if (apr_dso_sym(&modsym, modhandle, modname) != APR_SUCCESS) {
        char my_error[256];

        return apr_pstrcat(cmd->pool, "Can't locate API module structure `",
                          modname, "' in file ", module_file, ": ",
                          apr_dso_error(modhandle, my_error, sizeof(my_error)),
                          NULL);
    }
    modp = (module*) modsym;
    modp->dynamic_load_handle = (apr_dso_handle_t *)modhandle;
    modi->modp = modp;

    /*
     * Make sure the found module structure is really a module structure
     *
     */
    if (modp->magic != MODULE_MAGIC_COOKIE) {
        return apr_psprintf(cmd->pool, "API module structure '%s' in file %s "
                            "is garbled - expected signature %08lx but saw "
                            "%08lx - perhaps this is not an Apache module DSO, "
                            "or was compiled for a different Apache version?",
                            modname, module_file,
                            MODULE_MAGIC_COOKIE, modp->magic);
    }

    /*
     * Add this module to the Apache core structures
     */
    error = ap_add_loaded_module(modp, cmd->pool, modname);
    if (error) {
        return error;
    }

    /*
     * Register a cleanup in the config apr_pool_t (normally pconf). When
     * we do a restart (or shutdown) this cleanup will cause the
     * shared object to be unloaded.
     */
    apr_pool_cleanup_register(cmd->pool, modi, unload_module, apr_pool_cleanup_null);

    /*
     * Finally we need to run the configuration process for the module
     */
    ap_single_module_configure(cmd->pool, cmd->server, modp);

    return NULL;
}

/*
 * This implements the LoadFile directive and loads an arbitrary
 * shared object file into the adress space of the server process.
 */

static const char *load_file(cmd_parms *cmd, void *dummy, const char *filename)
{
    apr_dso_handle_t *handle;
    const char *used_file, *error;

    error = dso_load(cmd, &handle, filename, &used_file);
    if (error)
        return error;

    ap_log_error(APLOG_MARK, APLOG_DEBUG, 0, NULL, APLOGNO(01576)
                 "loaded file %s", used_file);

    return NULL;
}

static module *ap_find_loaded_module_symbol(server_rec *s, const char *modname)
{
    so_server_conf *sconf;
    ap_module_symbol_t *modi;
    ap_module_symbol_t *modie;
    int i;

    sconf = (so_server_conf *)ap_get_module_config(s->module_config,
                                                   &so_module);
    modie = (ap_module_symbol_t *)sconf->loaded_modules->elts;

    for (i = 0; i < sconf->loaded_modules->nelts; i++) {
        modi = &modie[i];
        if (modi->name != NULL && strcmp(modi->name, modname) == 0) {
            return modi->modp;
        }
    }
    return NULL;
}

static void dump_loaded_modules(apr_pool_t *p, server_rec *s)
{
    ap_module_symbol_t *modie;
    ap_module_symbol_t *modi;
    so_server_conf *sconf;
    int i;
    apr_file_t *out = NULL;

    if (!ap_exists_config_define("DUMP_MODULES")) {
        return;
    }

    apr_file_open_stdout(&out, p);

    apr_file_printf(out, "Loaded Modules:\n");

    sconf = (so_server_conf *)ap_get_module_config(s->module_config,
                                                   &so_module);
    for (i = 0; ; i++) {
        modi = &ap_prelinked_module_symbols[i];
        if (modi->name != NULL) {
            apr_file_printf(out, " %s (static)\n", modi->name);
        }
        else {
            break;
        }
    }

    modie = (ap_module_symbol_t *)sconf->loaded_modules->elts;
    for (i = 0; i < sconf->loaded_modules->nelts; i++) {
        modi = &modie[i];
        if (modi->name != NULL) {
            apr_file_printf(out, " %s (shared)\n", modi->name);
        }
    }
}

#else /* not NO_DLOPEN */

static const char *load_file(cmd_parms *cmd, void *dummy, const char *filename)
{
    ap_log_perror(APLOG_MARK, APLOG_STARTUP, 0, cmd->pool, APLOGNO(01577)
                 "WARNING: LoadFile not supported on this platform");
    return NULL;
}

static const char *load_module(cmd_parms *cmd, void *dummy,
                               const char *modname, const char *filename)
{
    ap_log_perror(APLOG_MARK, APLOG_STARTUP, 0, cmd->pool, APLOGNO(01578)
                 "WARNING: LoadModule not supported on this platform");
    return NULL;
}

#endif /* NO_DLOPEN */

static void register_hooks(apr_pool_t *p)
{
#ifndef NO_DLOPEN
    APR_REGISTER_OPTIONAL_FN(ap_find_loaded_module_symbol);
    ap_hook_test_config(dump_loaded_modules, NULL, NULL, APR_HOOK_MIDDLE);
#endif
}

static const command_rec so_cmds[] = {
    AP_INIT_TAKE2("LoadModule", load_module, NULL, RSRC_CONF | EXEC_ON_READ,
      "a module name and the name of a shared object file to load it from"),
    AP_INIT_ITERATE("LoadFile", load_file, NULL, RSRC_CONF  | EXEC_ON_READ,
      "shared object file or library to load into the server at runtime"),
    { NULL }
};

AP_DECLARE_MODULE(so) = {
   STANDARD20_MODULE_STUFF,
   NULL,                 /* create per-dir config */
   NULL,                 /* merge per-dir config */
   so_sconf_create,      /* server config */
   NULL,                 /* merge server config */
   so_cmds,              /* command apr_table_t */
   register_hooks        /* register hooks */
};