Configuration API for Apache HTTP ServerConfiguration API for Apache HTTP Server

William A. Rowe Jr.wrowe@apache.orgWilliam A. Rowe Jr.wrowe@apache.org

ConfigurationConfigurationConfigurationConfigurationregister_hooks Function (upon load)register_hooks Function (upon load)

pre_config Hook (prior to conf processing)pre_config Hook (prior to conf processing)

{ Configuration Command Processing }{ Configuration Command Processing }

post_config Hook (after .conf files processed)post_config Hook (after .conf files processed)

register_hooks Function (upon load)register_hooks Function (upon load)

pre_config Hook (prior to conf processing)pre_config Hook (prior to conf processing)

{ Configuration Command Processing }{ Configuration Command Processing }

post_config Hook (after .conf files processed)post_config Hook (after .conf files processed)

Module IdentiferModule IdentiferModule IdentiferModule IdentiferAP_DECLARE_MODULE(foo) = AP_DECLARE_MODULE(foo) = {{ STANDARD20_MODULE_STUFF, STANDARD20_MODULE_STUFF, create_dir_foo_config, create_dir_foo_config, merge_dir_foo_config, merge_dir_foo_config, create_server_foo_config, create_server_foo_config, merge_server_foo_config, merge_server_foo_config, foo_cmds, foo_cmds, register_foo_hooks register_foo_hooks};};

AP_DECLARE_MODULE(foo) = AP_DECLARE_MODULE(foo) = {{ STANDARD20_MODULE_STUFF, STANDARD20_MODULE_STUFF, create_dir_foo_config, create_dir_foo_config, merge_dir_foo_config, merge_dir_foo_config, create_server_foo_config, create_server_foo_config, merge_server_foo_config, merge_server_foo_config, foo_cmds, foo_cmds, register_foo_hooks register_foo_hooks};};

http_config.hhttp_config.hhttp_config.hhttp_config.h● Defines command_struct, members Defines command_struct, members

of the command list arrayof the command list array● Offers common directive handlers Offers common directive handlers

(on|off, int value etc)(on|off, int value etc)● Offers prototypes for command handlersOffers prototypes for command handlers● Defines the macro wrappers for individual Defines the macro wrappers for individual

command list entriescommand list entries

● Defines command_struct, members Defines command_struct, members of the command list arrayof the command list array

● Offers common directive handlers Offers common directive handlers (on|off, int value etc)(on|off, int value etc)

● Offers prototypes for command handlersOffers prototypes for command handlers● Defines the macro wrappers for individual Defines the macro wrappers for individual

command list entriescommand list entries

command_structcommand_structcommand_structcommand_structstruct command_struct {struct command_struct { const char *name; const char *name; cmd_func func; /* custom or stock handler */ cmd_func func; /* custom or stock handler */ void *cmd_data; /* presented as cmd->info */ void *cmd_data; /* presented as cmd->info */ int req_override; int req_override; enum cmd_how args_how; enum cmd_how args_how; const char *errmsg; const char *errmsg;};};

struct command_struct {struct command_struct { const char *name; const char *name; cmd_func func; /* custom or stock handler */ cmd_func func; /* custom or stock handler */ void *cmd_data; /* presented as cmd->info */ void *cmd_data; /* presented as cmd->info */ int req_override; int req_override; enum cmd_how args_how; enum cmd_how args_how; const char *errmsg; const char *errmsg;};};

cmd_how – what scope?cmd_how – what scope?cmd_how – what scope?cmd_how – what scope?● TAKE1, TAKE2, TAKE3 TAKE1, TAKE2, TAKE3

– fixed number of args– fixed number of args● TAKE12 TAKE23, TAKE 13, TAKE123 TAKE12 TAKE23, TAKE 13, TAKE123

– alternative number of args– alternative number of args● ITERATE – invoke TAKE1 multiple timesITERATE – invoke TAKE1 multiple times● ITERATE2 – TAKE2, first arg is repeatedITERATE2 – TAKE2, first arg is repeated

● TAKE1, TAKE2, TAKE3 TAKE1, TAKE2, TAKE3 – fixed number of args– fixed number of args

● TAKE12 TAKE23, TAKE 13, TAKE123 TAKE12 TAKE23, TAKE 13, TAKE123 – alternative number of args– alternative number of args

● ITERATE – invoke TAKE1 multiple timesITERATE – invoke TAKE1 multiple times● ITERATE2 – TAKE2, first arg is repeatedITERATE2 – TAKE2, first arg is repeated

cmd_how – more scopescmd_how – more scopescmd_how – more scopescmd_how – more scopes● NO_ARGS – Directive is simply presentNO_ARGS – Directive is simply present● FLAG – boolean valueFLAG – boolean value● TAKE_ARGV – an argv[], argc style listTAKE_ARGV – an argv[], argc style list● RAW_ARGS – the unprocessed stringRAW_ARGS – the unprocessed string

● NO_ARGS – Directive is simply presentNO_ARGS – Directive is simply present● FLAG – boolean valueFLAG – boolean value● TAKE_ARGV – an argv[], argc style listTAKE_ARGV – an argv[], argc style list● RAW_ARGS – the unprocessed stringRAW_ARGS – the unprocessed string

Directive WrappersDirective WrappersDirective WrappersDirective Wrappers● Simplifies command_struct element Simplifies command_struct element

declarationdeclaration● Cleanly formatted, typesafe handler Cleanly formatted, typesafe handler

referencesreferences

● Simplifies command_struct element Simplifies command_struct element declarationdeclaration

● Cleanly formatted, typesafe handler Cleanly formatted, typesafe handler referencesreferences

Stock FunctionsStock FunctionsStock FunctionsStock Functions● ap_set_string_slotap_set_string_slot● ap_set_int_slotap_set_int_slot● ap_set_string_slot_lowerap_set_string_slot_lower● ap_set_flag_slotap_set_flag_slot● ap_set_flag_slot_charap_set_flag_slot_char● ap_set_file_slotap_set_file_slot

● ap_set_string_slotap_set_string_slot● ap_set_int_slotap_set_int_slot● ap_set_string_slot_lowerap_set_string_slot_lower● ap_set_flag_slotap_set_flag_slot● ap_set_flag_slot_charap_set_flag_slot_char● ap_set_file_slotap_set_file_slot

Stock ArgsStock ArgsStock ArgsStock Args● cmd_data must be the field offset within cmd_data must be the field offset within

the server or dir config structurethe server or dir config structure● Config merge must still be handled by the Config merge must still be handled by the

module authormodule author● ap_set_deprecated is a no-op, warning ap_set_deprecated is a no-op, warning

stock handlerstock handler

● cmd_data must be the field offset within cmd_data must be the field offset within the server or dir config structurethe server or dir config structure

● Config merge must still be handled by the Config merge must still be handled by the module authormodule author

● ap_set_deprecated is a no-op, warning ap_set_deprecated is a no-op, warning stock handlerstock handler

Scope OptionsScope OptionsScope OptionsScope Options● RSRC_CONF - Global/VHost scope onlyRSRC_CONF - Global/VHost scope only● ACCESS_CONF - Per-dir/htaccess scopeACCESS_CONF - Per-dir/htaccess scope● OR_LIMIT, _OPTIONS, _FILEINFO, OR_LIMIT, _OPTIONS, _FILEINFO,

_AUTHCFG, _INDEXES, and _ALL_AUTHCFG, _INDEXES, and _ALL● - Enforce specific AllowOverride (OR_ALL - Enforce specific AllowOverride (OR_ALL

for anywhere)for anywhere)

● RSRC_CONF - Global/VHost scope onlyRSRC_CONF - Global/VHost scope only● ACCESS_CONF - Per-dir/htaccess scopeACCESS_CONF - Per-dir/htaccess scope● OR_LIMIT, _OPTIONS, _FILEINFO, OR_LIMIT, _OPTIONS, _FILEINFO,

_AUTHCFG, _INDEXES, and _ALL_AUTHCFG, _INDEXES, and _ALL● - Enforce specific AllowOverride (OR_ALL - Enforce specific AllowOverride (OR_ALL

for anywhere)for anywhere)

More OptionsMore OptionsMore OptionsMore OptionsEXEC_ON_READ EXEC_ON_READ

– – Invoke command handler immediatelyInvoke command handler immediately(Otherwise invoked after the tree is read)(Otherwise invoked after the tree is read)

NONFATAL_OVERRIDE, _UNKNOWN, or _ALL NONFATAL_OVERRIDE, _UNKNOWN, or _ALL

– – proceed if AllowOverride violated or out of proceed if AllowOverride violated or out of scopescope

EXEC_ON_READ EXEC_ON_READ

– – Invoke command handler immediatelyInvoke command handler immediately(Otherwise invoked after the tree is read)(Otherwise invoked after the tree is read)

NONFATAL_OVERRIDE, _UNKNOWN, or _ALL NONFATAL_OVERRIDE, _UNKNOWN, or _ALL

– – proceed if AllowOverride violated or out of proceed if AllowOverride violated or out of scopescope

Tour of ExamplesTour of ExamplesTour of ExamplesTour of Examples● mod_env – simple per-dir examplemod_env – simple per-dir example● mod_mime – reusing a single functionmod_mime – reusing a single function

for many commands (per-dir scope)for many commands (per-dir scope)● mod_so – EXEC_ON_READ examplemod_so – EXEC_ON_READ example● mod_userdir – Raw args (server scope)mod_userdir – Raw args (server scope)

● mod_env – simple per-dir examplemod_env – simple per-dir example● mod_mime – reusing a single functionmod_mime – reusing a single function

for many commands (per-dir scope)for many commands (per-dir scope)● mod_so – EXEC_ON_READ examplemod_so – EXEC_ON_READ example● mod_userdir – Raw args (server scope)mod_userdir – Raw args (server scope)

Questions?Questions?Questions?Questions?