Deutsche Version

mod_daytime

Multi Protocol Support is one of the most important new features in Apache 2: The server is able to handle other TCP network services than just HTTP. As an example, the default distribution of Apache 2 HTTPD contains the mod_echo module that implements the Echo protocol. This standard TCP service answers any request by returning its complete contents. As a result, it can be helpful in testing network connections.

Based on the source code of mod_echo, I have written the mod_daytime module. It implements the Daytime Service according to RFC 867. This service answers any request by sending the current date and time. The RFC doesn't specify a format; this implementation is using ctime(3).

The module only provides a single configuration directive:

It is usually recommended to create a virtual host that works as a Daytime server exclusively. You might configure it for TCP port 13 on which the Daytime Service listens by default. The configuration to achieve that looks like this:

# Listen on Port 13
Listen 13

<VirtualHost *:13>
   ProtocolDaytime On
</VirtualHost>

The first thing you need to do, however, is compile the source code provided here. On a UNIX system where Apache 2 has been installed with DSO support, you can simply type the following command (as root):

# [/path/of/apache/bin/]apxs -cia mod_daytime.c

This will create the DSO file mod_daytime.so, copy it into the Apache installation's /modules directory, and add the following directive for loading the module to httpd.conf:

LoadModule daytime_module modules/mod_daytime.c

Module Source Code Explained

Like all Apache modules, mod_daytime is written in ANSI C and makes use of the Apache API. Therefore, it starts with a few preprocessor directives to include the API header files as well as the standard library file time.h:

#include "ap_config.h"
#include "ap_mmn.h"
#include "httpd.h"
#include "http_config.h"
#include "http_connection.h"

#include "apr_buckets.h"
#include "util_filter.h"
#include <time.h>

The next line is a forward declaration of the module structure. This is common in Apache modules as module functions sometimes refer to that structure:

module AP_MODULE_DECLARE_DATA daytime_module;

The module structure's definition itself, however, is usually located at the end of the file (more precisely: at the end of the module's main source file mod_xxx.c, if a module is made up of more than one file):

/* Module Structure */
module AP_MODULE_DECLARE_DATA daytime_module = {
    STANDARD20_MODULE_STUFF,
    NULL,                       /* Per-Directory Configuration */
    NULL,                       /* Directory Config Merger */
    create_daytime_server_config,  /* Per-Server Configuration */
    NULL,                       /* Server Config Merger */
    daytime_cmds,                  /* Command Table (Directives) */
    register_hooks              /* Registering Hooks */
};

As you can see, each module can contain functions for per-directory configuration, for merging nested directory configurations, for per-server configuration, and for merging server configurations. The last two entries are the command table to set up the module's configuration directives, and the hook registration funcion that determines at what time during HTTP transactions the module's services will be used. The module structure contains a pointer to each of these funtions or data structures. Any reference that you don't need can be simply set to NULL. Besides, any Apache 2 module needs the symbolic constant STANDARD20_MODULE_STUFF.

Next, a data structure is defined to store the module's configuration data. mod_daytime only needs a single int value, set to 0 for ProtocolDaytime Off (default) and to 1 for ProtocolDaytime On.

/* Config Data Structure */
typedef struct {
    int dt_enabled;
} daytime_config;

Please note that some modules declare two different configuration data structures because their possible per-server and per-directory-settings differ. mod_daytime has only got a per-server configuration as you might already have seen from the module structure.

The create_daytime_server_config() function allocates the memory needed for the configuration settings and sets their default value - 0 in this case as an equivalent for "turned off". This function is invoked automatically because of the appropriate pointer in the module structure. Here is its source code:

/* Create per-server configuration */
static void *create_daytime_server_config(apr_pool_t *p, server_rec *s)
{
    daytime_config *conf = apr_pcalloc(p, sizeof *conf);

    conf->dt_enabled = 0;

    return conf;
}

The predefined value can be overridden by setting the ProtocolEcho directive. When this directive is encountered, the following function will be called:

/* Process the ProtocolDaytime directive */
static const char *daytime_on(cmd_parms *cmd, void *dummy, int arg)
{
    daytime_config *conf = ap_get_module_config(cmd->server->module_config,
                                                &daytime_module);
    conf->dt_enabled = arg;

    return NULL;
}

The module's core functionality is provided by the process_daytime_connection() function. It starts by reading the current Server's or virtual host's configuration and simply returns DECLINED ("not my business") if dt_enabled is set to false. If not, it creates a so-called bucket brigade for server response data using an Apache API function. It writes the date and time formatted by ctime() into the brigade. This is the function's full source code:

/* Process the daytime connection */
static int process_daytime_connection(conn_rec *c)
{
    apr_bucket_brigade *bb;
    apr_bucket *b;
    apr_status_t rv;
    time_t now;
    daytime_config *conf = ap_get_module_config(c->base_server->module_config,
                                               &daytime_module);

    if (!conf->dt_enabled) {
        return DECLINED;
    }

    bb = apr_brigade_create(c->pool, c->bucket_alloc);

    now = time (NULL);
    
    ap_fprintf(c->output_filters, bb, "%s\r\n", ctime(&now));
    ap_fflush(c->output_filters, bb);

    return OK;
}

The above mentioned command table defines the directive and determines the function to be called when it is encountered:

/* Directive */
static const command_rec daytime_cmds[] =
{
    AP_INIT_FLAG("ProtocolDaytime", daytime_on, NULL, RSRC_CONF,
                 "Run a daytime server on this host"),
    { NULL }
};

The type constant AP_INIT_FLAG is used for directives that take in one of the values On and Off. They will be automatically converted to 1 or 0, respectively. There are several other type constants for different kinds of directives, like AP_INIT_TAKE1 for exactly one literal value.

The last element to be described is the register_hooks() function. Using hooks, you can determine the phase of HTTP request processing in which you want your module's functions to operate. There are numerous hooks that define phases, including server startup, configuration processing, client-request reading, response creation, and output filtering. mod_daytime defines an application protocol other than HTTP, so the correct hook is process_connection: The module only needs to know that there has been a request (with any contents). Daytime does not deal with details like soecified protocol commands, and the usual HTTP parser is not necessary either. Here's the code of the register_hooks() function:

/* Register Hooks */
static void register_hooks(apr_pool_t *p)
{
    ap_hook_process_connection(process_daytime_connection, NULL, NULL,
                               APR_HOOK_MIDDLE);
}

You can download mod_daytime here.