Prototypes and functions for the SQL module. More...

#include <freeradius-devel/server/base.h>
#include <freeradius-devel/server/pool.h>
#include <freeradius-devel/server/modpriv.h>
#include <freeradius-devel/server/exfile.h>
#include <freeradius-devel/server/trunk.h>
#include <freeradius-devel/unlang/function.h>

Include dependency graph for rlm_sql.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	fr_sql_map_ctx_t
	Context used when fetching attribute value pairs as a map list. More...

struct	fr_sql_query_t

struct	rlm_sql_config_t

struct	rlm_sql_driver_t

struct	rlm_sql_escape_uctx_t

struct	rlm_sql_handle_t

struct	rlm_sql_thread_t

struct	sql_inst

struct	sql_log_entry_t

struct	sql_state_entry_t

Macros
#define	FR_ITEM_CHECK 0

#define	FR_ITEM_REPLY 1

#define	RLM_SQL_MULTI_QUERY_CONN 2
	Can support multiple queries on a single connection. More...

#define	RLM_SQL_RCODE_FLAGS_ALT_QUERY 1
	Can distinguish between other errors and those. More...

Typedefs
typedef char **	rlm_sql_row_t

typedef struct sql_inst	rlm_sql_t

typedef size_t(*	sql_error_t) (TALLOC_CTX ctx, sql_log_entry_t out[], size_t outlen, fr_sql_query_t handle)
	Retrieve errors from the last query operation. More...

Enumerations
enum	fr_sql_query_status_t { SQL_QUERY_FAILED = -1 , SQL_QUERY_PREPARED = 0 , SQL_QUERY_SUBMITTED , SQL_QUERY_RETURNED , SQL_QUERY_FETCHING_RESULTS , SQL_QUERY_RESULTS_FETCHED , SQL_QUERY_CANCELLED }
	Status of an SQL query. More...

enum	fr_sql_query_type_t { SQL_QUERY_SELECT , SQL_QUERY_OTHER }

enum	sql_fall_through_t { FALL_THROUGH_NO = 0 , FALL_THROUGH_YES , FALL_THROUGH_DEFAULT }

enum	sql_rcode_t { RLM_SQL_QUERY_INVALID = -3 , RLM_SQL_ERROR = -2 , RLM_SQL_OK = 0 , RLM_SQL_RECONNECT = 1 , RLM_SQL_ALT_QUERY , RLM_SQL_NO_MORE_ROWS }
	Action to take at end of an SQL query. More...

Functions
fr_sql_query_t *	fr_sql_query_alloc (TALLOC_CTX ctx, rlm_sql_t const inst, request_t request, rlm_sql_handle_t handle, trunk_t trunk, char const query_str, fr_sql_query_type_t type)
	Allocate an sql query structure. More...

unlang_action_t	rlm_sql_fetch_row (rlm_rcode_t p_result, UNUSED int priority, request_t request, void uctx)
	Call the driver's sql_fetch_row function. More...

void	rlm_sql_print_error (rlm_sql_t const inst, request_t request, fr_sql_query_t *query_ctx, bool force_debug)
	Retrieve any errors from the SQL driver. More...

unlang_action_t	rlm_sql_query (rlm_rcode_t p_result, int priority, request_t request, void uctx)

void	rlm_sql_query_log (rlm_sql_t const inst, char const filename, char const *query)

unlang_action_t	rlm_sql_select_query (rlm_rcode_t p_result, UNUSED int priority, request_t request, void uctx)
	Call the driver's sql_select_query method, reconnecting if necessary. More...

unlang_action_t	rlm_sql_trunk_query (rlm_rcode_t p_result, UNUSED int priority, request_t request, void uctx)
	Submit an SQL query using a trunk connection. More...

unlang_action_t	sql_get_map_list (request_t request, fr_sql_map_ctx_t map_ctx, rlm_sql_handle_t *handle, trunk_t trunk)
	Submit the query to get any user / group check or reply pairs. More...

void *	sql_mod_conn_create (TALLOC_CTX ctx, void instance, fr_time_delta_t timeout)

int	sql_state_entries_from_cs (fr_trie_t states, CONF_SECTION overrides)
	Insert the contents of a CONF_SECTION into the state trie. More...

int	sql_state_entries_from_table (fr_trie_t *states, sql_state_entry_t const table[])
	Insert the contents of a state table into the state trie. More...

sql_state_entry_t const *	sql_state_entry_find (fr_trie_t const states, char const sql_state)
	Lookup an SQL state based on an error code returned from the SQL server or client library. More...

fr_trie_t *	sql_state_trie_alloc (TALLOC_CTX *ctx)
	Allocate a sql_state trie, and insert the initial set of entries. More...

Variables
fr_table_num_sorted_t const	sql_rcode_description_table []

size_t	sql_rcode_description_table_len

fr_table_num_sorted_t const	sql_rcode_table []

size_t	sql_rcode_table_len

Detailed Description

Prototypes and functions for the SQL module.

Id: 76d359c8268173a106db85087ae0b6395f143df8

Copyright: 2012-2014 Arran Cudbard-Bell (a.cud.nosp@m.bard.nosp@m.b@fre.nosp@m.erad.nosp@m.ius.o.nosp@m.rg); 2000,2006 The FreeRADIUS server project; 2000 Mike Machado (mike@.nosp@m.inne.nosp@m.rcite.nosp@m..com); 2000 Alan DeKok (aland.nosp@m.@fre.nosp@m.eradi.nosp@m.us.o.nosp@m.rg)

Definition in file rlm_sql.h.

Data Structure Documentation

◆ fr_sql_map_ctx_t

struct fr_sql_map_ctx_t

Context used when fetching attribute value pairs as a map list.

Definition at line 154 of file rlm_sql.h.

Collaboration diagram for fr_sql_map_ctx_t:

Data Fields
TALLOC_CTX *	ctx	To allocate map entries in.
rlm_sql_t const *	inst	Module instance data.
fr_dict_attr_t const *	list	Default list for pair evaluation.
map_list_t *	out	List to append entries to.
fr_value_box_t *	query	Query string used for fetching pairs.
fr_sql_query_t *	query_ctx	Query context.
int	rows	How many rows the query returned.

◆ fr_sql_query_t

struct fr_sql_query_t

Definition at line 137 of file rlm_sql.h.

Collaboration diagram for fr_sql_query_t:

Data Fields
rlm_sql_handle_t *	handle	Connection handle this query is being run on.
rlm_sql_t const *	inst	Module instance for this query.
char const *	query_str	Query string to run.
sql_rcode_t	rcode	Result code.
request_t *	request	Request this query relates to.
rlm_sql_row_t	row	Row data from the last query.
fr_sql_query_status_t	status	Status of the query.
trunk_connection_t *	tconn	Trunk connection this query is being run on.
trunk_request_t *	treq	Trunk request for this query.
trunk_t *	trunk	Trunk this query is being run on.
fr_sql_query_type_t	type	Type of query.
void *	uctx	Driver specific data.

◆ rlm_sql_config_t

struct rlm_sql_config_t

Definition at line 73 of file rlm_sql.h.

Collaboration diagram for rlm_sql_config_t:

Data Fields
char const *	allowed_chars	Chars which done need escaping..
bool	cache_groups	cache group names in &control.SQL-Group
char const *	connect_query	Query executed after establishing new connection.
char const *	group_attribute	Name of the group attribute.
fr_time_delta_t	query_timeout	How long to allow queries to run for.
bool	read_groups	Read user groups by default. If false, Fall-Through = yes is required in the previous reply list to process groups.
bool	read_profiles	Read user profiles by default. If false, Fall-Through = yes is required in the previous reply list to process profiles.
char const *	sql_db	Database to run queries against.
char const *	sql_login	Login credentials to use.
char const *	sql_password	Login password to use.
uint32_t	sql_port	Port to connect to.
char const *	sql_server	Server to connect to.
trunk_conf_t	trunk_conf	Configuration for trunk connections.

◆ rlm_sql_escape_uctx_t

struct rlm_sql_escape_uctx_t

Definition at line 198 of file rlm_sql.h.

Collaboration diagram for rlm_sql_escape_uctx_t:

Data Fields
rlm_sql_handle_t *	handle
rlm_sql_t const *	sql

◆ rlm_sql_handle_t

struct rlm_sql_handle_t

Definition at line 113 of file rlm_sql.h.

Collaboration diagram for rlm_sql_handle_t:

Data Fields
void *	conn	Database specific connection handle.
rlm_sql_t const *	inst	The rlm_sql instance this connection belongs to.
TALLOC_CTX *	log_ctx	Talloc pool used to avoid allocing memory when log strings need to be copied.

◆ rlm_sql_thread_t

struct rlm_sql_thread_t

Definition at line 107 of file rlm_sql.h.

Collaboration diagram for rlm_sql_thread_t:

Data Fields
rlm_sql_t const *	inst	Module instance data.
void *	sql_escape_arg	Thread specific argument to be passed to escape function.
trunk_t *	trunk	Trunk connection for this thread.

◆ sql_log_entry_t

struct sql_log_entry_t

Definition at line 61 of file rlm_sql.h.

Data Fields
char const *	msg	Log message.
fr_log_type_t	type	Type of log entry L_ERR, L_WARN, L_INFO, L_DBG etc.

◆ sql_state_entry_t

struct sql_state_entry_t

Definition at line 67 of file rlm_sql.h.

Data Fields
char const *	meaning	Verbose description.
sql_rcode_t	rcode	What should happen if we receive this error.
char const *	sql_state	2-5 char error code.

Macro Definition Documentation

◆ FR_ITEM_CHECK

#define FR_ITEM_CHECK 0

Definition at line 37 of file rlm_sql.h.

◆ FR_ITEM_REPLY

#define FR_ITEM_REPLY 1

Definition at line 38 of file rlm_sql.h.

◆ RLM_SQL_MULTI_QUERY_CONN

#define RLM_SQL_MULTI_QUERY_CONN 2

Can support multiple queries on a single connection.

Definition at line 174 of file rlm_sql.h.

◆ RLM_SQL_RCODE_FLAGS_ALT_QUERY

#define RLM_SQL_RCODE_FLAGS_ALT_QUERY 1

Can distinguish between other errors and those.

resulting from a unique key violation.

Definition at line 173 of file rlm_sql.h.

Typedef Documentation

◆ rlm_sql_row_t

typedef char** rlm_sql_row_t

Definition at line 59 of file rlm_sql.h.

◆ rlm_sql_t

typedef struct sql_inst rlm_sql_t

Definition at line 59 of file rlm_sql.h.

◆ sql_error_t

typedef size_t(* sql_error_t) (TALLOC_CTX *ctx, sql_log_entry_t out[], size_t outlen, fr_sql_query_t *handle)

Retrieve errors from the last query operation.

Note: Buffers allocated in the context provided will be automatically freed. The driver should not free these buffers explicitly.; If the driver uses its own buffers to aggregate messages, they should be cleared on sql_query_finish, and after each call to sql_error, to prevent the same messages being printed multiple times.

Parameters

[in,out]	ctx	to allocate any buffers required. If static buffers are provided by the driver they need not be talloc_strdupd, just write the pointer to those buffers to the .msg field of a sql_log_entry_t element.
[out]	out	a pre-allocated array of log entries to fill. Need not be NULL terminated.
[in]	outlen	Number of log entries available for populating. Do not write to index out[outlen] or higher.
[in]	handle	to retrieve errors from.
[in]	config	of the SQL instance.

Returns: 0 - If no error messages are available. >0 - Number of log entries

Definition at line 196 of file rlm_sql.h.

Enumeration Type Documentation

◆ fr_sql_query_status_t

enum fr_sql_query_status_t

Status of an SQL query.

Enumerator
SQL_QUERY_FAILED	Failed to submit.
SQL_QUERY_PREPARED	Ready to submit.
SQL_QUERY_SUBMITTED	Submitted for execution.
SQL_QUERY_RETURNED	Query has executed.
SQL_QUERY_FETCHING_RESULTS	Fetching results from server.
SQL_QUERY_RESULTS_FETCHED	Results fetched from the server.
SQL_QUERY_CANCELLED	A cancellation has been sent to the server.

Definition at line 127 of file rlm_sql.h.

◆ fr_sql_query_type_t

enum fr_sql_query_type_t

Enumerator
SQL_QUERY_SELECT
SQL_QUERY_OTHER

Definition at line 120 of file rlm_sql.h.

◆ sql_fall_through_t

enum sql_fall_through_t

Enumerator
FALL_THROUGH_NO
FALL_THROUGH_YES
FALL_THROUGH_DEFAULT

Definition at line 53 of file rlm_sql.h.

◆ sql_rcode_t

enum sql_rcode_t

Action to take at end of an SQL query.

Enumerator
RLM_SQL_QUERY_INVALID	Query syntax error.
RLM_SQL_ERROR	General connection/server error.
RLM_SQL_OK	Success.
RLM_SQL_RECONNECT	Stale connection, should reconnect.
RLM_SQL_ALT_QUERY	Key constraint violation, use an alternative query.
RLM_SQL_NO_MORE_ROWS	No more rows available.

Definition at line 44 of file rlm_sql.h.

Function Documentation

◆ fr_sql_query_alloc()

fr_sql_query_t* fr_sql_query_alloc	(	TALLOC_CTX *	ctx,
		rlm_sql_t const *	inst,
		request_t *	request,
		rlm_sql_handle_t *	handle,
		trunk_t *	trunk,
		char const *	query_str,
		fr_sql_query_type_t	type
	)

Allocate an sql query structure.

Definition at line 413 of file sql.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rlm_sql_fetch_row()

unlang_action_t rlm_sql_fetch_row	(	rlm_rcode_t *	p_result,
		UNUSED int *	priority,
		request_t *	request,
		void *	uctx
	)

Call the driver's sql_fetch_row function.

Calls the driver's sql_fetch_row logging any errors. On success, will write row data to uctx->row.

The rcode within the query context is updated to

RLM_SQL_OK on success.
other sql_rcode_t constants on error.

Parameters

p_result	Result of current module call.
priority	Unused.
request	Current request.
uctx	query context containing query to execute.

Returns: an unlang_action_t.

Definition at line 308 of file sql.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rlm_sql_print_error()

void rlm_sql_print_error	(	rlm_sql_t const *	inst,
		request_t *	request,
		fr_sql_query_t *	query_ctx,
		bool	force_debug
	)

Retrieve any errors from the SQL driver.

Retrieves errors from the driver from the last operation and writes them to to request/global log, in the ERROR, WARN, INFO and DEBUG categories.

Parameters

inst	Instance of rlm_sql.
request	Current request, may be NULL.
query_ctx	Query context to retrieve errors for.
force_debug	Force all errors to be logged as debug messages.

Definition at line 352 of file sql.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rlm_sql_query()

unlang_action_t rlm_sql_query	(	rlm_rcode_t *	p_result,
		int *	priority,
		request_t *	request,
		void *	uctx
	)

Here is the caller graph for this function:

◆ rlm_sql_query_log()

void rlm_sql_query_log	(	rlm_sql_t const *	inst,
		char const *	filename,
		char const *	query
	)

Definition at line 774 of file sql.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rlm_sql_select_query()

unlang_action_t rlm_sql_select_query	(	rlm_rcode_t *	p_result,
		UNUSED int *	priority,
		request_t *	request,
		void *	uctx
	)

Call the driver's sql_select_query method, reconnecting if necessary.

Note: Caller must call (inst->driver->sql_finish_select_query)(handle, &inst->config); after they're done with the result.

The rcode within the query context is updated to

RLM_SQL_OK on success.
RLM_SQL_RECONNECT if a new handle is required (also sets the handle to NULL).
RLM_SQL_QUERY_INVALID, RLM_SQL_ERROR on invalid query or connection error.
RLM_SQL_ALT_QUERY on constraints violation.

Parameters

p_result	Result of current module call.
priority	Unused.
request	Current request.
uctx	query context containing query to execute.

Returns: an unlang_action_t.

Definition at line 646 of file sql.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rlm_sql_trunk_query()

unlang_action_t rlm_sql_trunk_query	(	rlm_rcode_t *	p_result,
		UNUSED int *	priority,
		request_t *	request,
		void *	uctx
	)

Submit an SQL query using a trunk connection.

Parameters

p_result	Result of current module call.
priority	Unused.
request	Current request.
uctx	query context containing query to execute.

Returns: an unlang_action_t.

Definition at line 572 of file sql.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sql_get_map_list()

unlang_action_t sql_get_map_list	(	request_t *	request,
		fr_sql_map_ctx_t *	map_ctx,
		rlm_sql_handle_t **	handle,
		trunk_t *	trunk
	)

Submit the query to get any user / group check or reply pairs.

Definition at line 756 of file sql.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sql_mod_conn_create()

void* sql_mod_conn_create	(	TALLOC_CTX *	ctx,
		void *	instance,
		fr_time_delta_t	timeout
	)

Definition at line 65 of file sql.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sql_state_entries_from_cs()

int sql_state_entries_from_cs	(	fr_trie_t *	states,
		CONF_SECTION *	cs
	)

Insert the contents of a CONF_SECTION into the state trie.

The attribute side of the CONF_PAIR specifies the sqlclass and the value specifies the error code.

Parameters

[in]	states	Trie of states.
[in]	cs	Containing overrides to define new sql state entries or change existing ones.

Returns

0 on success.
-1 on failure.

Definition at line 153 of file sql_state.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sql_state_entries_from_table()

int sql_state_entries_from_table	(	fr_trie_t *	states,
		sql_state_entry_t const	table[]
	)

Insert the contents of a state table into the state trie.

Parameters

[in]	states	Trie of states.
[in]	table	to insert.

Returns

0 on success.
-1 on failure.

Definition at line 124 of file sql_state.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sql_state_entry_find()

sql_state_entry_t const* sql_state_entry_find	(	fr_trie_t const *	states,
		char const *	sql_state
	)

Lookup an SQL state based on an error code returned from the SQL server or client library.

Parameters

[in]	states	Trie of states.
[in]	sql_state	to lookup.

Returns

An sql_state_entry_t with the sql_rcode_t associated with the sql state.
NULL if no entry exists.

Definition at line 203 of file sql_state.c.

Here is the call graph for this function:

◆ sql_state_trie_alloc()

fr_trie_t* sql_state_trie_alloc ( TALLOC_CTX * ctx )

Allocate a sql_state trie, and insert the initial set of entries.

Parameters

[in] ctx to allocate states in.

Returns

SQL state trie on success.
NULL on failure.

Definition at line 102 of file sql_state.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ sql_rcode_description_table

fr_table_num_sorted_t const sql_rcode_description_table[]

extern

Definition at line 45 of file sql.c.

◆ sql_rcode_description_table_len

size_t sql_rcode_description_table_len

extern

Definition at line 53 of file sql.c.

◆ sql_rcode_table

fr_table_num_sorted_t const sql_rcode_table[]

extern

Definition at line 55 of file sql.c.

◆ sql_rcode_table_len

size_t sql_rcode_table_len

extern

Definition at line 63 of file sql.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Data Structure Documentation

◆ fr_sql_map_ctx_t

◆ fr_sql_query_t

◆ rlm_sql_config_t

◆ rlm_sql_escape_uctx_t

◆ rlm_sql_handle_t

◆ rlm_sql_thread_t

◆ sql_log_entry_t

◆ sql_state_entry_t

Macro Definition Documentation

◆ FR_ITEM_CHECK

◆ FR_ITEM_REPLY

◆ RLM_SQL_MULTI_QUERY_CONN

◆ RLM_SQL_RCODE_FLAGS_ALT_QUERY

Typedef Documentation

◆ rlm_sql_row_t

◆ rlm_sql_t

◆ sql_error_t

Enumeration Type Documentation

◆ fr_sql_query_status_t

◆ fr_sql_query_type_t

◆ sql_fall_through_t

◆ sql_rcode_t

Function Documentation

◆ fr_sql_query_alloc()

◆ rlm_sql_fetch_row()

◆ rlm_sql_print_error()

◆ rlm_sql_query()

◆ rlm_sql_query_log()

◆ rlm_sql_select_query()

◆ rlm_sql_trunk_query()

◆ sql_get_map_list()

◆ sql_mod_conn_create()

◆ sql_state_entries_from_cs()

◆ sql_state_entries_from_table()

◆ sql_state_entry_find()

◆ sql_state_trie_alloc()

Variable Documentation

◆ sql_rcode_description_table

◆ sql_rcode_description_table_len

◆ sql_rcode_table

◆ sql_rcode_table_len