Directive changes for Apache
---------------------------Between revisions of Apache httpd and other Apache modules, it's
necessary to identify all of the directive changes which have slipped by
without much notice or attention, particularly for the httpd docs.
cmp_cmds.pl is a script to review two configuration summaries, created by
the mod_cmds module, and summarize the differences. This comparison is
not exahustive, but simply a review of the key identifiers, such as the
arguments type (which may change for valid reasons without impact to the
documentation), the contexts in which the directive is permitted, and the
descriptive text provided for the user. The script will also make note
of transitions when a directive is relocated from one module to another,
when it is introduced, or deprecated.
It's critical that two servers to compare using cmd_cmds.pl are
configured
with precisely the same modules loaded, although the order is
unimportant.
Building mod_cmds
----------------You may build mod_cmds using apxs on unix or Win32
apxs -c mod_cmds.c
apxs -i mod_cmds.so
Invoking mod_cmds
----------------mod_cmds dumps a complete detail of all recognized Apache commands as
part of the startup phase. It's not intended to be used in any running
server, but can be conviently invoked against a server with command;
bin/httpd -c "LoadModule cmds_module modules/mod_cmds.so" -t >cmd.lst
By using the -t{est} flag, the server will not start, but simply run the
mod_cmds output to stdout after parsing the httpd.conf file, and exit.
Note that any misconfiguration, e.g. syntax errors in httpd.conf, will
prevent the module from loading.
All desired modules should be configured to load as part of the Apache
startup. Therefore, it may be necessary to -DSSL as well, to include the
ssl module itself.
mod_cmds Output
--------------The output is in the format;
mod_setenvif.c::SetEnvIf
RAW_ARGS OR_FILEINFO
c A header-name, regex and a list of variables.
or in other words;
module::directive
<sp>ARGS_TYPE<sp>[OR_OPTS<sp>]...
<sp>description
The output is ment to be parsed by cmp_cmds, and discrepancies between
modules containing the directives, the args or command options, and the
actually directive description can be compared between two servers of
different configurations or generations. Therefore this output format
isn't terribly sophisticated.
Invoking cmp_cmds
----------------The cmp_cmds.pl tool takes the results of two invocations of mod_cmds,
and summarizes the output. To invoke cmp_cmds, use the syntax;
./cmp_cmds.pl [--desc] orig_mod_cmds_output new_mod_cmds_output
where --desc will include descriptive changes, otherwise changes to the
descriptions are omitted. An example illustrating the changes reported
appears as;
AcceptFilter deprecated from http_core.c
AccessFileName moved from http_core.c to core.c
AddInputFilter introduced in mod_mime.c
CacheNegotiatedDocs options changed
..from NO_ARGS RSRC_CONF
....to FLAG RSRC_CONF
CacheNegotiatedDocs description changed
..from no arguments (either present or absent)
....to Either 'on' or 'off' (default)
Which should be relatively self explanatory, except for;
Directive Options
----------------The first keyword of the 'options' list is always the argument processing
that applies to the given Directive;
NO_ARGS No arguments allowed (present or absent)
FLAG
One argument expected (On or Off)
TAKE1 Exactly one argument is expected.
TAKE12 Between one and two arguments are expected.
TAKE123 Between one and three arguments are expected.
TAKE13 Either one or three arguments are expected.
TAKE2 Exactly two arguments are expected.
TAKE23 Either two or three arguments are expected.
TAKE3 Exactly three arguments are expected.
ITERATE Unlimited arguments that each of similar meaning.
ITERATE2
One argument, followed by arguments of similar meaning.
RAW_ARGS
This provides no hint of the accepted arguments,
since this directive's own code parses the arguments.
Additional keywords of the 'options' list is the context and special
flags
that apply to the given Directive;
OR_NONE not available anywhere outside of this override
OR_LIMIT
valid in .htaccess with AllowOverride Limit
and inside <Directory> or <Location>
OR_OPTIONS
valid in .htaccess with AllowOverride Options
and anywhere within a conf
OR_FILEINFO valid in .htaccess with AllowOverride FileInfo
and anywhere within a conf
OR_AUTHCFG
valid in .htaccess with AllowOverride AuthConfig
and inside <Directory> or <Location>
OR_INDEXES
valid in .htaccess with AllowOverride Indexes
and anywhere within a conf
OR_UNSET
unset a directive (in Allow)
ACCESS_CONF valid inside <Directory> or <Location>
RSRC_CONF
valid outside <Directory> or <Location>
EXEC_ON_READ
this directive executes a command which modifies
configuration processing (such as loading a module
that introduces more Directives.)
Introduced in 2.0, this flag wasn't needed in
Apache 1.3 to have the same effect.
ToDo
---XMLify?
Need better explanations of the OR sections.
History
------2001.12.04 wrowe
Created initial mod_cmds.c compatible with Apache 1.3 and 2.0.
2001.12.05 wrowe
Created initial cmp_cmds.pl script to parse mod_cmds output
and report discrepancies.