Chapter 8:  Modules

Stronghold uses a modular architecture that consists of a core Apache server enhanced by a number of modules. Each module implements a different feature set, and you can add, remove, enable, or disable modules to change the total feature set of your server.

This chapter explains

• Stronghold's modules
  

  By default, most of the included modules are compiled into Stronghold during installation. "Stronghold Modules" on page 8-3 describes each of the modules distributed with Stronghold Web Server 3.0 and indicates which ones are compiled into the server by default.

• how to add and remove modules
  

  There are several different methods of adding and removing modules from the server. "Adding and Removing Modules" on page 8-6 compares these methods and describes how to use each one.

Since Stronghold's resource requirements are directly proportional to the size of the binary, you may want to pare the server down by removing modules you don't need. You can find out which modules are active in at any time by accessing the server information report described in "Server Information Reports" on page 1-13, or by using the -l flag with the httpsd command:

In addition to the modules bundled with Stronghold, many third-party modules are available through the Apache Module Registry at http://modules.apache.org/ Apache modules are compatible with Stronghold. If you are interested in writing your own modules for Stronghold, consult the Apache API Notes at http://www.apache.org/docs/API.html

Stronghold Modules

Each of Stronghold's modules supports a discrete feature set, and most modules utilize configuration directives. In Chapter 3, each directive entry specifies the module associated with that directive. You can only use a directive if its supporting module is active. If you remove a module, be sure to comment out its directives in httpd.conf, or use <IfModule> to exclude it dynamically as described in "Containers" on page 6-2.

The following modules are bundled with Stronghold, though not all are compiled in by default:

Before you decide to remove one of these modules, be sure you know how its absence affects Stronghold's functionality. For example, you can safely remove mod_status if you are not interested in real-time, HTML-formatted status reports. Removing mod_ssl, however, is not recommended because any HTTPS request will fail.

Adding and Removing Modules

Stronghold Web Server 3.0 provides three different methods of adding and removing modules:

• dynamic shared object (DSO) support

  Dynamic shared object support, provided by mod_so, allows the server to load modules at startup without first having them compiled into the server binary. Under this efficient new scheme, only the server core and mod_so need to be compiled together; all other modules can be loaded at startup.

• dynamic module linking

  Dynamic module linking saves time by allowing you to edit httpd.conf and reload the server to change the set of active modules. However, it requires that all modules be compiled into the server binary.

• recompiling the server binary

  The traditional method of adding and removing modules is to recompile the Stronghold binary executable file with a different set of modules. This can take longer, but it can also result in a leaner binary if you do not need to change the module set frequently.

Dynamic Shared Object Support

Dynamic shared object (DSO) support allows the server to load modules at startup instead of having them compiled into the server binary. DSO is supported by mod_so, which must be compiled in statically. When mod_so and the server core are compiled statically, they can load other modules at startup that are designated in httpd.conf. DSO support also allows multiple instances of the server to run with different module sets configured with different httpd.conf files.

Although DSO provides a convenient way to add and remove modules quickly, dynamically loaded modules do not perform as efficiently as statically compiled modules. It is recommended that all necessary modules be compiled statically, and that only new, temporary, or seldom-used modules be loaded dynamically.

In order to use DSO support, you must;

• edit the Configuration file so that the server core is compiled with mod_so and other required modules and modules that should be dynamically loadable are converted to shared object files

  This usually needs to be done only once, although you can repeat the process to add DSO support for any third-party modules that you later acquire. After that, the modules that have been converted to shared object files are always available for loading at startup.

• edit the httpd.conf file so that the modules you want to activate are listed for loading at server startup or restart

  This can easily be done whenever you want to change the set of dynamically loaded modules.

• Switch to the <ServerRoot>/src/ directory.
• Open the Configuration file using a text editor.
• Make sure the following line is uncommented:

  AddModule modules/standard/mod_so.o
  

  This module must be compiled into Stronghold in order to support DSO.

• For each module that you want to be able to load dynamically, change the AddModule directive to SharedModule.
  

• If you have acquired raw source code for third-party modules that you want to load dynamically, add a new SharedModule line for each.

• In all SharedModules lines, change the .o module filename extension to .so. For example, the following line
  

  SharedModule modules/standard/mod_dir.o
  

  should be changed to

  SharedModule modules/standard/mod_dir.so
  

• Run Configure:

  # ./Configure

• Rebuild HTTPSD:

  # make

• Stop the server:

  # ../bin/stop-server

• Back up the old binary:

  # mv ../httpsd ../httpsd-bak

• Install the new binary:

  # cp httpsd ..
  

The modules designated with SharedModule are now available as shared object files. Before you start the server again (with the <ServerRoot>/bin/start-server script), you must edit httpd.conf and specify the shared object files that the server will load on startup.

• Open the <ServerRoot>/conf/httpd.conf file using a text editor.
• In the global server configuration (above all containers in the file), use a LoadModule directive for each module that the server should load at startup.

• The LoadModule directive has a syntax similar to that of the obsolete Configuration Module directive. For example:

  LoadModule status_module src/modules/mod_status.so

• Use a LoadFile directive for each additional object file to load at startup.

  The LoadFile directive facilitates patches and other auxiliary object code. Its value is one or filenames, either in an absolute path or relative to ServerRoot. For example:

  LoadFile src/enreq.so

• Remove modules that should not be loaded at startup either by deleting their LoadModule lines or commenting them out.
• Save the modified server configuration file.
• Restart the server:

  # ServerRoot/bin/reload-server
  

Dynamic Module Linking

Stronghold's dynamic module linking system allows you to change the set of active modules without recompiling the server, provided that all the modules you want to use are already compiled. You can use this feature to streamline Stronghold's feature set, but you cannot use it to add modules that are not already compiled. For example, you could recompile Stronghold with all available modules, then use dynamic module linking to narrow down the number of modules that Stronghold actually uses.

The list of modules that are currently compiled is the default list of "active" modules. Dynamic linking first "clears" this list, then applies a new list that Stronghold reads from the httpd.conf file each time it starts. This simplifies module configuration, because you only need to edit httpd.conf and restart Stronghold to implement module changes.

• In httpd.conf, add the following line:

  ClearModuleList

  This clears the default list of active modules.

• Add the AddModule directive, followed by a new list of active modules. For example:

  AddModule mod_ssl mod_cgi mod_dir mod_userdir mod_alias
  

  Use the module names as they appear in the ServerRoot/src/Configuration file.

• Save the modified httpd.conf file.
  
• Switch to the <ServerRoot> directory.
  
• Restart Stronghold by stopping and then starting it:

  # bin/stop-server
  # bin/start-server
  

  	You must use this method instead of the reload-server script whenever you change the dynamic module list.

If you want to remove an active module, simply delete it from the AddModule list and restart Stronghold. Likewise, you can add modules to the list at any time, then restart Stronghold to implement them.

Recompiling Stronghold

The Configuration file already contains the code you need to install any module that comes with Stronghold, including the optional modules described later in this chapter. The precompiled modules described on page 8-3 are compiled into Stronghold when you first install it. Optional modules are commented out of Configuration. By uncommenting a line of module code, you can recompile the server to include that module. Commenting out a line of module code and recompiling the server excludes the module.

If you want to reconfigure the PHP module for database support, you must follow the instructions in "Recompiling The PHP Modules" on page 11-3, then recompile Stronghold as described in this section.

The order of the module list in Configuration affects how the modules are compiled. In general, use these guidelines for dealing with the module list:

• Do not change the order of the module list unless you are sure you know what you are doing.
• If you add third-party modules to the list, place them at the bottom of the list, but above mod_ssl.
• Always remove a module by commenting it out rather than deleting it, so that you do not lose its place in the list.

Many third-party modules have not been thoroughly tested for use with Stronghold 3.0 and Apache 1.3.1. If you have an existing server with third-party modules that you wish to compile into Stronghold 3.0, do so with caution. When using an existing Configuration file or modifying the new Configuration file to include new modules, note these changes:

• The source code has been reorganized; modules are now located in subdirectories of a new <ServerRoot>/src/modules/ directory.
• The Module directive has been changed to AddModule.
• The EXTRA_LFLAGS variable has been changed to EXTRA_LDFLAGS.
• The -DMAXIMUM_DNS definition is now obsolete.
• The -DSERVER_SUBVERSION=\"string\" compile-time option has been replaced with the run-time API call ap_add_version_component().
• The mod_dir module has been divided into mod_dir and mod_autoindex.
• The mod_auth_msql module is no longer included in the distribution.

To edit Configure and recompile Stronghold

• Switch to the <ServerRoot>/scr directory:

  # cd <ServerRoot>/src

  	This is the directory created during installation, and it may vary from the default.

• Edit the Configuration file to reflect which modules or patches you want.
  • To add an existing module, uncomment the module code line by removing the opening hash mark (#).
    
  • To add a new module, place it at the end of the module list using the following syntax:
    AddModule modules/directory/object.o
    Always use a path relative to ServerRoot/src/.
    
  • To remove a module, comment it out by adding a hash mark to the beginning of the module code line.
    
• Save the modified Configuration file.
  
• To add a patch, use the patch utility to specify the patch you want to install:

  # patch -s < patchfile

• Run Configure:

  # ./Configure

• Rebuild HTTPSD:

  # make

• Stop the server:

  # ../bin/stop-server

• Back up the old binary:

  # mv ../httpsd ../httpsd-bak

• Install the new binaries: # cp httpsd ..

• Start the server: # ../bin/start-server