FreeSWITCH mod_xml_radius module documentation
Digging in 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 sources were studied and the text is written below. I hope he helps someone. The text is written so that it is understandable already working with FreeSWITCH. Therefore, I do not advise starting an introduction to FreeSWITCH with this text.
Separately, I want to note that some (very small) changes were made to the source code of the module, more details at the end of the publication.
The module currently (14/10/2014) has virtually no documentation. All the fabrications below are obtained upon studying the source codes, thematic mailing lists and the rest of the documentation (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 is included with the source, add a section:
If the sections such as auth_invite and auth_reg are defined in the module’s configuration file (only the auth_invite section is checked in the source module and the parameters are loaded and checked obviously abnormally, it’s very similar to the author’s slip that made copy-paste blocks and forgot to change the variable name in two places), the module bindit requests processing section of the global configuration
The module fills in RADIUS requests in accordance with its own config and dictionaries supplied. Each value of the name of the parameter string is assigned a value from the Channel variable specified by the variable value (and if there is no such channel variable, then the value from variable_secondary) in accordance with the format string.
The module defines its own handlers for global events of the switch .on_routing and .on_reporting:
Events are generated when the channel state changes to ROUTING and REPORTING, respectively. At least one triggering condition (condition) must be defined in the acct_start and acct_end sections of the configuration file, 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 transmit to RADIUS the information on these switch events, which are obtained from Channel variables. Each name value of the parameter string 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 authentication is successful, and a negative value (which RADIUS returned) if not. The result of the execution is written to the radius_auth_result channel variable. Also, if sets of AV pairs came in RADIUS’s response, the application creates and populates the corresponding channel variables without adding leading radius_s to the name of the variables (at least I didn’t find the radius_ add code).
Separately, according to my changes to the source code of the module. They make cosmetic changes to debug messages and correct the fact that IMHO is a typo of the author. diff to module in below. Unfortunately, I can’t say in which version of the source I work (I am not good at using git). At the time of writing, the version is current, diff is generated using git diff from the root source folder.
Separately, I want to note that some (very small) changes were made to the source code of the module, more details at the end of the publication.
The module currently (14/10/2014) has virtually no documentation. All the fabrications below are obtained upon studying the source codes, thematic mailing lists and the rest of the documentation (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 is included with the source, add a section:
<global><paramname="debug"value="7"/></global>If the sections such as auth_invite and auth_reg are defined in the module’s configuration file (only the auth_invite section is checked in the source module and the parameters are loaded and checked obviously abnormally, it’s very similar to the author’s slip that made copy-paste blocks and forgot to change the variable name in two places), the module bindit requests processing section of the global configuration
<paramname="xml-handler-bindings"value="directory"/>The module fills in RADIUS requests in accordance with its own config and dictionaries supplied. Each value of the name of the parameter string is assigned a value from the Channel variable specified by the variable value (and if there is no such channel variable, then the value from variable_secondary) in accordance with the format string.
The module defines its own handlers for global events of the switch .on_routing and .on_reporting:
1135staticconst 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 when the channel state changes to ROUTING and REPORTING, respectively. At least one triggering condition (condition) must be defined in the acct_start and acct_end sections of the configuration file, 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 transmit to RADIUS the information on these switch events, which are obtained from Channel variables. Each name value of the parameter string 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 authentication is successful, and a negative value (which RADIUS returned) if not. The result of the execution is written to the radius_auth_result channel variable. Also, if sets of AV pairs came in RADIUS’s response, the application creates and populates the corresponding channel variables without adding leading radius_s to the name of the variables (at least I didn’t find the radius_ add code).
Separately, according to my changes to the source code of the module. They make cosmetic changes to debug messages and correct the fact that IMHO is a typo of the author. diff to module in below. Unfortunately, I can’t say in which version of the source I work (I am not good at using git). At the time of writing, the version is current, diff is generated using git diff from the root source folder.
diff --git a/src/mod/xml_int/mod_xml_radius/mod_xml_radius.c b/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);
}