Documentation for the mod_xml_radius module from FreeSWITCH

Delving into the network, I did not find the documentation. The task is to configure this module, so that later it can be transferred to support. Accordingly, the source code was studied and the text below was written. I hope he will help someone. The text is written so that it would be clear already working with FreeSWITCH. Therefore, I advise you not to start acquaintance with FreeSWITCH from this text.



Separately, I want to note that some (very small) changes were made to the source code of the module, in more detail at the end of the publication.



The module at the moment (10/14/2014) has practically no documentation. All the fabrications below have been obtained on the basis of the fact of studying the sources, thematic mailing lists and documentation residues (including the change history) wiki.freeswitch.org/wiki/Mod_xml_radius .



Debug does not turn on from the console (why - HZ, did not understand). To include it in the module configuration file, an example of which comes with the source code, add a section:

')

<global> <param name="debug" value="7"/> </global> 

The value can be any other than 0 (checked as a Boolean variable).



If in the configuration file of the module such sections are defined as: auth_invite and auth_reg (in the initial module only the presence of the auth_invite section is checked and the parameters are loaded and they are obviously not normal, very similar to the author’s copy-paste and forgot to change the variable name in two places), then the module bindit processing requests for the global configuration section

 <param name="xml-handler-bindings" value="directory"/> 

on its own function of working with events and requests using the standard mod_xml_curl mechanism (see the corresponding documentation on the Frisvich website). In this case, real work occurs only if the sip_auth_method field of the event being processed is defined and has the value “INVITE” or “REGISTER”. In this case, an XML config is returned to the switch, according to which the switch can authenticate itself.



The module fills RADIUS requests according to its own config and the dictionaries supplied in the kit. Each value of the name of the parameter string is assigned a value from a channel variable (Channel variable) specified by the value of the variable (and if there is no such variable, the value from variable_secondary) in accordance with the format string.



The module defines its own handlers for global switch events .on_routing and .on_reporting:

 1135 static const switch_state_handler_table_t state_handlers = { 1136 /*.on_init */ NULL, 1137 /*.on_routing */ mod_xml_radius_accounting_start, 1138 /*.on_execute */ NULL, 1139 /*.on_hangup */ NULL, 1140 /*.on_exchange_media */ NULL, 1141 /*.on_soft_execute */ NULL, 1142 /*.on_consume_media */ NULL, 1143 /*.on_hibernate */ NULL, 1144 /*.on_reset */ NULL, 1145 /*.on_park */ NULL, 1146 /*.on_reporting */ mod_xml_radius_accounting_end 1147 }; 

Events are generated at the moment when the channel status changes to ROUTING and REPORTING, respectively. In the acct_start and acct_end sections of the configuration file, at least one trigger condition (condition) must be defined, otherwise an error is generated when loading the config section (not a fact, you need to check, because the code does not confirm this, this information was found somewhere in network). These handlers send RADIUS information on these switch events, which are obtained from the channel variables. Each value of the name of the parameter line of the corresponding section of the configuration file is assigned a value from the channel variable specified by the variable value (and if it is not in the channel variables, then from variable_secondary) in accordance with the format value.



In the case of calling radius_auth (an application that can be called from the configuration file), the authorization result in RADIUS is returned (as text): 0 if the authentication is successful, and a negative value (which was returned by RADIUS) if not. The result of the execution is written to the channel variable radius_auth_result. Also, if the AV pairs came in the RADIUS response, the application creates and populates the corresponding channel variables without adding the leading radius_ in the variable names (at least I did not find the radius_ addition code).



Separately, according to my changes to the source of the module. They make cosmetic changes in messages debag and correct the fact that IMHO is a misprint of the author. diff to module in below. Unfortunately, I can’t say in which version of the source I work (I’m not good at using git). At the time of writing, the current version of the letter, diff is formed using git diff from the root source folder.

 diff --git a/src/mod/xml_int/mod_xml_radius/mod_xml_radius.cb/src/mod/xml_int/mod_xml_radius/mod_xml_radius.c index bc75843..94e127a 100644 --- a/src/mod/xml_int/mod_xml_radius/mod_xml_radius.c +++ b/src/mod/xml_int/mod_xml_radius/mod_xml_radius.c @@ -201,7 +201,7 @@ switch_status_t do_config() goto err; } } else { - switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_INFO, "Could not find 'auth_invite' section in config file.\n"); + switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_INFO, "Could not find 'auth_reg' section in config file.\n"); } if ((tmp = switch_xml_child(cfg, "global")) != NULL ) { @@ -741,7 +741,7 @@ switch_xml_t mod_xml_radius_auth_reg(switch_event_t *params) { switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "mod_xml_radius: starting registration authentication\n"); } - if ( mod_xml_radius_new_handle(&new_handle, globals.auth_invite_configs) != SWITCH_STATUS_SUCCESS ) { + if ( mod_xml_radius_new_handle(&new_handle, globals.auth_reg_configs) != SWITCH_STATUS_SUCCESS ) { switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "Failed to load radius handle for registration authentication\n"); goto err; } @@ -849,7 +849,7 @@ static switch_xml_t mod_xml_radius_directory_search(const char *section, const c switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "mod_xml_radius: starting authentication\n"); switch_event_serialize(params, &event_buf, SWITCH_TRUE); switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "Event: %s \n", event_buf); - switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "Section: %s \nTag: %s\nKey_name: %s\nKey_value: %s\n", + switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "\nSection: %s \nTag: %s\nKey_name: %s\nKey_value: %s\n", section, tag_name, key_name, key_value); } @@ -1087,7 +1087,7 @@ SWITCH_STANDARD_APP(radius_auth_handle) temp = NULL; if ( result != 0 ) { - switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "mod_xml_radius: Failed to authenticate\n"); + switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "mod_xml_radius: Failed to authenticate, authentication result: %d \n", result); goto err; } @@ -1169,7 +1169,7 @@ SWITCH_MODULE_LOAD_FUNCTION(mod_xml_radius_load) return SWITCH_STATUS_TERM; } - if ( globals.auth_invite_configs ) { + if ( globals.auth_invite_configs && globals.auth_reg_configs ) { status = switch_xml_bind_search_function(mod_xml_radius_directory_search, switch_xml_parse_section_string("directory"), NULL); }