Chapter 7: Third-Party Modules

• mod_auth_cookies_file
  • Directives
    • Cookie_Access
    • Cookie_AuthFile
    • Cookie_Authorative
    • Cookie_MustGive
    • Cookie_EncryptedCookies
• mod_auth_cookies_msql
  • Directives
    • Cookie_Access
    • Cookie_Authorative
    • Cookie_MustGive
    • Cookie_MSQL_table
    • Cookie_MSQLcookie_namefield
    • Cookie_MSQLcookie_valuefield
    • Cookie_MSQLdatabase
    • Cookie_MSQLhost
    • Cookie_MSQLuid_field
    • Cookie_EncryptedCookies
• mod_userpath
  • Directive
    • UserPath
• mod_cgi_sugid
  • Directives
    • UserID
    • GroupID
• mod_auth_sys
• mod_perl and mod_perl_fast
• mod_auth_external
  • Directives
    • AddExternalAuth
    • AuthExternal
    • AddExternalGroup
    • ExternalGroup
• mod_auth_kerb
  • Directives
    • AuthType
    • KrbAuthRealm
    • RedirectHttps
• mod_fontxlate
• mod_cntr
• mod_sucgi
• mod_auth_dbi
  • Directives
    • AuthDBIAuth
    • AuthDBIDB
    • AuthDBIDriver
    • AuthDBINameField
    • AuthDBIPasswordField
    • AuthDBIUser
    • AuthDBIUserTable
• mod_rewrite
• mod_neoinclude
• mod_xinclude (XSSI)
• mod_php
• Summary

Third-Party Modules

There is a wide range of modules developed by third parties for Apache that extend the functionality of the server in some useful way. Following the belief that it is better to reuse and enhance than to recreate, this chapter covers some of the third-party modules registered with the Apache Module Registry. The registry can be found at http://www.zyzzzyva.com/server/module_registry (see Figure 7.1).

Figure 7.1. The home page of the Apache Module Registry.

mod_auth_cookies_file

This module is designed to allow transparent authentication to users who have previously registered with your site. Suppose that you want to have visitors register with you before they access your software download area. By collecting information from them and then issuing a persistent cookie, the next time they visit your download area they can forgo the authentication procedure.

Cookies are a Netscape extension. The official reference for Netscape cookies can be found at http://home.netscape.com/newsref/std/cookie_spec.html.

A cookie allows the browser to identify itself every time it makes a request. A cookie is no more than a ticket. When you go to your dry cleaner and give them clothes for cleaning, they give you a ticket. That ticket identifies you as having brought clothes in for cleaning; it associates you with your clothes. You can think of the dry cleaner's ticket as a cookie.

There are two types of cookies: persistent and temporary. Persistent cookies get recorded in the visitor's computer for use later. When the browser makes subsequent requests to the same URL, it first checks to see if it has a cookie for it. If it does, the browser includes this information in the HTTP request header where a program in the server (a CGI or a module) can use this information for any purpose it wants. Temporary cookies are only used during the duration of the visit, after which they are discarded.

A Netscape persistent cookie is set with an HTTP header like the following:

Set-Cookie: Name=value; [Expires=date;] [Path=path;] [Domain=domainname;] [Secure]

The Set-Cookie header can be embedded in an HTML document in a META tag, like the following, or from a CGI:

<META HTTP-EQUIV="Set-Cookie" CONTENT="Customer=John Doe"; Path=/; Domain=www.domain.com"> 

When sent from a CGI, this information must be sent as part of the HTTP header. For more information on how to form a header, please refer to Chapter 5, "CGI (Common Gateway Interface) Programming."

Name specifies the name identifier for the cookie.

value can be any information you want to keep track of.

The Expires option sets a date that will be used for expiring the cookie. If not specified, the cookie will expire at the end of the current session, making it a temporary cookie. The format is Wdy, DD-Mon-YY HH:MM:SS GMT. Wdy is the day of the week; possible values for Wdy are Mon, Tue, Wed, Thu, Fri, Sat, or Sun. DD is the day of the month; possible values are 01–31. Mon is the month; possible values for it are Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, or Dec. YY is the last two digits of the year, without the century (1996=96). HH specifies the hour in a 24-hour format. MM specifies the minutes, and SS specifies the seconds. The date should be specified in the Greenwich Mean Time (GMT) time zone. Previously issued cookies can be expired by sending a new cookie with the same name using an expiration date that has already past. Expiration depends on the visitor's clock time, which may be far off from the real time.

The Path option specifies the document hierarchy where the cookie is valid. This is typically set to / so that it is valid for all documents in the document hierarchy. The browser uses this information to determine if there are any cookies already stored in the visitor's computer that are associated with path. If there are, the browser returns a Cookie: header along with the cookie Name and value along with the request. Multiple cookies matching the path will be sent with semicolons separating them.

Domain specifies the Internet domain where the cookie is valid. You can specify a fully qualified domain name such as host.domain.com.

When Secure is specified, the cookie will only be sent if the connection is secure by using a Secure Socket Layer (SSL) server, such as Stronghold.

The mod_auth_cookies_file module requests a named cookie from the client that contains the authentication information, which gets verified against an htpasswd like database.

Directives

mod_auth_cookie_file provides five directives:

• Cookie_Access
  
  
• Cookie_AuthFile
  
  
• Cookie_Authorative
  
  
• Cookie_MustGive
  
  
• Cookie_EncryptedCookies
  
  

Cookie_Access

This directive sets cookie access authentication.

Cookie_AuthFile

The format of the authentication file (authFile) is a list of colon (:)-separated values following this format:

userId:name:value

where userID is the user's name, name is the cookie name, and value is the cookie value.

Cookie_Authorative

If the cookie fails, no authorization is given (authorization is final.) The user will have to re-register with the site before she is able to log in.

Cookie_MustGive

When set to on, the client must present a cookie prior to authenticating.

Cookie_EncryptedCookies

This module specifies if the cookie value is encrypted using crypt—the program used by UNIX to encrypt passwords.

mod_auth_cookies_msql

This module is similar to mod_auth_cookie_file, but uses mini-SQL (mSQL) to store its authentication data. It is designed to allow transparent authentication to users who have previously registered with your site. Suppose that you want to have visitors register with you before they access your software download area. By collecting information from them and then issuing a persistent cookie, the next time they visit your download area they can forgo the authentication procedure.

This module will request a named cookie from the client that contains the authentication information, which gets verified against tables in a mSQL database.

Directives

Mod_auth_cookie_msql provides 10 directives:

• Cookie_Access
  
  
• Cookie_Authorative
  
  
• Cookie_EncryptedCookies
  
  
• Cookie_MSQL_table
  
  
• Cookie_MSQLcookie_namefield
  
  
• Cookie_MSQLcookie_valuefield
  
  
• Cookie_MSQLdatabase
  
  
• Cookie_MSQLhost
  
  
• Cookie_MSQLuid_field
  
  
• Cookie_MustGive
  
  

Cookie_Access

This directive sets cookie access authentication.

Cookie_Authorative

If the cookie fails, no authorization is given (authorization is final). The user will need to re-register with the site.

Cookie_MustGive

When set to on, the client must present a cookie prior to authenticating.

Cookie_MSQL_table

Cookie_MSQL_table sets the name of the mSQL table that contains the username and cookie fields used for authentication.

Cookie_MSQLcookie_namefield

Cookie_MSQLcookie_namefield sets the name of the field from which the module will fetch the name of the cookie.

Cookie_MSQLcookie_valuefield

Cookie_MSQLcookie_valuefield sets the name of the field from which the module will fetch the value of the cookie.

Cookie_MSQLdatabase

Cookie_MSQLdatabase sets the name of the mSQL database that contains the Cookie_MSQL_table where the authentication information is stored.

Cookie_MSQLhost

This directive sets the name of the host machine running the mSQL server. The name of the host can be specified using its fully qualified domain name, its IP address, or localhost to specify that the server running the database is the same as the Web server.

Cookie_MSQLuid_field

Cookie_MSQLuid_field sets the name of the field from which the module will fetch the username or the uid.

Cookie_EncryptedCookies

This directive specifies if the cookie value is encrypted using crypt—the program used by UNIX to encrypt passwords.

mod_userpath

This module is a replacement for the mod_userdir module distributed with versions of Apache earlier than 1.1. The version of mod_userdir distributed with Apache 1.1.1 provides this functionality and more.

mod_userpath rewrites the URI of requests following the pattern:

http://machine/~username

This module allows you to specify a directory where the server will look for a user's home page. This module has the added benefit of allowing you to create home page directories that don't necessarily match your internal usernames. Because this mechanism doesn't rely on user accounts, it allows you to provide home pages on machines that don't contain any user information.

If you incorporate this module into Apache, you should remove mod_userdir because both of these modules will attempt to rewrite the URI, and which one will win is anyone's guess.

Directive

mod_userpath adds one directive:

• UserPath
  
  

UserPath

Requests ending in a username will have UserPath prepended before they are processed by the server. For example:

http://machine/~username

will be translated into

http://machine/usr/local/etc/httpd/htdocs/~username

mod_cgi_sugid

This module is a replacement for the standard Apache CGI module, mod_cgi. It provides the capability to run CGI under the User ID (UID) and Group ID (GID) of a different user. UID and GID can be specified inside the <Limit> sections. <Limit> sections are specified under <Location> or <Directory> sections in the global access configuration file. By default, this module does not allow the use of its directives from within per-directory access control files (.htaccess). Also, if the module fails to change the UID/GID of a CGI, the script is aborted. As you should expect, this module won't run CGI with a root UID.

Directives

mod_cgi_sugid adds two directives:

• UserId
  
  
• GroupId
  
  

UserID

The UserID directive sets the UID used to run a CGI. This directive rejects requests to run a CGI with the root UID.

GroupID

The GroupID directive sets the GID used to run a CGI.

mod_auth_sys

mod_auth_sys allows you to authenticate a user using the UNIX calls getpwnam_r and getgrnam_r to retrieve password and group information for that user. This allows you to use your existing UNIX authentication scheme, such as /etc/passwd files, Network Information Service (NIS), NIS++, and so on. This module does not provide any directives.

To call the module, just put an entry like the following in your global access configuration file or in a per-directory access file (omit the <Directory> section on per-directory access files):

<Directory somedir>
AuthType Basic
<Limit GET POST>
 require valid-user
</Limit>
</Directory>

The only concern with this module is the transmission of login and password information across the Internet because basic authentication does not encrypt the login transaction in any way. If anyone obtained this information in route, he would have full access to that user's account.

mod_perl and mod_perl_fast

mod_perl and mod_perl_fast provide an alternative method for executing Perl programs. mod_perl and mod_perl fast are not CGI, so the way you program them is a little different.

At the time of this writing, programs that you write to take advantage of these modules don't run from the command line without the aid of the CGI::Switch Perl module. CGI::Switch is available from your nearest CPAN archive at modules/by-module/Apache/CGI-XA-0_22305-alpha_tar.gz.

These modules embed a Perl interpreter in the Web server. Because the Perl interpreter is embedded, the server can run Perl scripts by itself, and your Perl programs will run much faster. The embedded interpreter eliminates much of the expense associated with running CGI on your Web server. Also, scripts that run under these modules have full access to the Application Programming Interface (API) of the server, giving you the option of writing modules using Perl.

These modules differ in the way they function. mod_perl allocates and constructs a Perl interpreter for each request. This interpreter parses and executes the script. On completion, the Perl interpreter is destroyed, freeing the resources that it consumed.

mod_perl_fast allocates and constructs one Perl interpreter when the server starts. It also loads and parses a Perl script that is persistent.

mod_auth_external

mod_auth_external allows you to specify an external program that will handle user and group authentication. The specified program will receive authentication information the visitor entered in the authentication panel via the USER and PASS environment variables. In addition, when doing group authentication, the group name is passed in the environment variable GROUP. The external authentication program is expected to return 0 to indicate successful authentication, or a nonzero result as an indication of a failed authentication session or an error in the authentication program.

This is a simple way of interfacing Apache to any authentication system.

Directives

mod_auth_external adds four directives:

• AddExternalAuth
  
  
• AuthExternal
  
  
• AddExternalGroup
  
  
• GroupExternal
  
  

AddExternalAuth

Adding the AddExternalAuth directive to your httpd.conf file will register userAuthenticator under token. You can have multiple AddExternalAuth directives.

AuthExternal

This directive is used inside a <Limit> section to specify the authenticator to use in this context. token gets matched to the AddExternalAuth directive, and the appropriate authenticator is launched:

<Directory somedir>
AuthName authentication realm description
AuthType Basic
AuthExternal token
<Limit GET POST>
 require valid-user
</Limit>
</Directory>

AddExternalGroup

Adding the AddExternalAuth directive to your httpd.conf file will register groupAuthenticator under token. You can have multiple AddExternalGroup directives.

ExternalGroup

This directive is used inside a <Limit> section to specify the authenticator to use in this context. token gets matched to the AddExternalGroup directive, and the appropriate authenticator is launched:

<Directory somedir>
AuthName authentication realm description
AuthType Basic
ExternalGroup token
<Limit GET POST>
 require group groupA
</Limit>
</Directory>

mod_auth_kerb

mod_auth_kerb provides kerberos authentication to Apache. Kerberos is a network security system designed at MIT that guarantees that users and services are who they claim to be without the need to ask a user for his password whenever he requests access to additional services. If the user's browser does not support kerberos directly, mod_auth_kerb will authenticate the user based on the user ID and password supplied to the browser.

Directives

mod_auth_kerb provides the following directives:

• AuthType
  
  
• KrbAuthRealm
  
  
• RedirectHttps
  
  

AuthType

This directive tells Apache and the browser which kerberos protocol to use when validating the user. This is the only directive necessary for the module to be functional.

KrbAuthRealm

The KbrAuthRealm directive takes one argument: a string specifying the kerberos realm name that the server should use for authentication. For example, KrbAuthRealm MIT.EDU sets the authentication realm to MIT.EDU.

RedirectHttps

This directive tells Apache to redirect the user's request to an SSL Web server running on the same host, if the original request was not under SSL. This allows for increased security on browsers that do not support kerberos directly by preventing clear text passwords from being sent over the network.

mod_fontxlate

mod_fontxlate is a configurable font-conversion module that determines if a request needs to be converted. Eastern European countries such as Slovenia use a variety of characters to represent local non-ASCII characters. Proper functioning of this module requires that Apache be patched. The advantage of this module is that it does its conversion very quickly.

For additional information, please refer to the documentation included in the module's source.

mod_cntr

This module and ancillary CGI provide a transparent way of implementing Web counters. The module will keep track of the page access count on ASCII or DBM databases. Because the Web server keeps count of page access, there's no possible spoofing of the pages. To be counted, a page needs to be delivered. This module comes with several different number styles.

When the page counter databases have been set with the provided utilities, displaying the counter is very easy. On the Web page, you put an entry such as

<img src="/cgi-bin/count?type=subdirectory length=numDigits">

where type specifies the subdirectory for the number type used and length is the number of digits to put in the output, including any padding.

mod_sucgi

This module is a drop-in replacement for the mod_cgi provided in the Apache release. It allows you to transparently change the UID of CGI scripts to match that of a user.

To enable the functionality, just add the following to your global access configuration file (access.conf):

<Directory userdir/*/cgi-bin>
Options ExecCGI
</Directory>

When the server receives a CGI request, it checks it see if it came from a UserDir. If it did, it will pass the request to a supporting CGI program, suCGI, which will check the request and run it with the UID of the appropriate user.

mod_auth_dbi

This module provides Perl DBI authentication. Database interface (DBI) provides a set of functions, variables, and conventions that you can use to access a database. This programming interface is independent of the database in use. For additional information on DBI, check http://www.hermetica.com/technologia/DBI.

Directives

Mod_auth_dbi adds the following directives:

• AuthDBIAuth
  
  
• AuthDBIDB
  
  
• AuthDBIDriver
  
  
• AuthDBINameField
  
  
• AuthDBIPasswordField
  
  
• AuthDBIUser
  
  
• AuthDBIUserTable
  
  

AuthDBIAuth

This directive sets the DBI password. It is optional, depending on the driver used.

AuthDBIDB

This directive sets the name of the database to use.

AuthDBIDriver

AuthDBIDriver sets the name of the DBI driver (for example, Oracle).

AuthDBINameField

This directive sets the fieldname within the AuthDBIUserTable in AuthDBIDB database where the username can be found.

AuthDBIPasswordField

This directive sets the fieldname within the AuthDBIUserTable in the AuthDBIDB database where the user's password can be found.

AuthDBIUser

This directive sets the user's DBI username. It is optional depending on the driver used.

AuthDBIUserTable

This directive sets the tablename within the AuthDBIDB database where the user and password fields can be found.

mod_rewrite

This is a killer module that even has its own Web site (see Figure 7.2). It uses a regular expression parser to rewrite requested URLs and can use external databases in both ASCII or DBM format for mapping support. This module has been incorporated into the Apache 1.2 release (not yet made public at the time of this writing). Apache 1.2 incorporates a built-in regular expression library. The latest version of mod_rewrite uses this library, which further reduces its impact on Apache.

Figure 7.2. This module also has a nice home page.

mod_rewrite can replace several modules, including some of the default Apache modules (when properly configured). This is great because it can provide more comprehensive functionality while reducing the number of modules needed and the size of the Apache executable.

This module can easily replace mod_alias, mod_userdir (both Apache core modules), mod_userdir_virtual (not covered in this book), mod_userpath, and mod_uri_remap.

If you don't have use for a fully configurable URI rewrite module, there's an additional module that will replace the mod_alias and mod_userdir. This module, mod_rewrite_compat, uses mod_rewrite to provide a plug-and-play replacement to those other two modules.

Oh, yes—and this is not a minor detail[dm] mod_rewrite, together with the FastCGI module documentation, is by far the best-documented piece of software available for Apache. This one edges out the FastCGI docs a bit and is easier to use, so it takes first place on my list. Documentation for both these modules is commercial grade, matching documentation produced by Apple Computer or NeXT Software, Inc. (the best documentation I has ever used). Most other modules feature rather thin information that requires users and authors alike to spend a lot of time experimenting with software before they can get it to work. This usually means diving into the source code to determine what really is going on. I didn't have to do that with this one.

For information on mod_rewrite, see Chapter 10, "Apache Modules."

mod_neoinclude

The neoinclude module processes NeoWebScript—a server-side scripting language based on Tcl. NeoWebScript programs can perform sophisticated data processing and dynamic HTML generation safely, without compromising the system. For comprehensive information on this module, please visit http://www.neosoft.com/neoscript.

mod_xinclude (XSSI)

This module implements and extends SSI functionality. In Apache 1.2, it replaces the standard SSI module (mod_include). This module provides additional functionality and directives over the Apache SSI module, including the following:

• User-defined variables
  
  
• An additional output directive, printenv
  
  
• Flow-control directives
  
  

XSSI (Extended SSI) supports the notion of user-defined variables, which you can use on all value tags with the exception of var= constructs. In addition to the echo, fsize, and flastmod commands, XSSI provides printenv, which prints all variables currently set (this includes CGI environment variables). XSSI also provides basic flow control. For more information on this module, refer to Chapter 6, "Server Side Includes (SSI)."

mod_php

This is a powerful SSI-type scripting language that provides a C-like syntax. Its main features include the following:

• Is supported via standard CGI, FastCGI, and Apache modules
  
  
• Access logging capabilities
  
  
• Built-in GUI-based configuration
  
  
• mSQL, Postgres95, and DBM support
  
  
• Supports a wide range of variables, arrays, and Perl-like associative arrays that can be passed from page to page
  
  
• Supports conditionals and while loops
  
  
• Supports regular expressions
  
  
• Provides raw HTTP header control for doing things like redirections
  
  
• Has on-the-fly GIF image support, with Thomas Boutell's GD library
  
  

For more information, please visit the PHP/FI home page listed at the top of this section.

Summary

While modules are great, remember that they get incorporated into the server binary. The more modules you add, the bigger the binary will get, which will increase the resources needed by your system to run the server efficiently. Remember that the server runs multiple copies of the Web server. So increasing the footprint by 100KB may translate into several megabytes depending on the number of server processes you have running. Your production server should only include the default Apache modules and any additional modules you absolutely need.