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_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.

#define	RLM_SQL_RCODE_FLAGS_ALT_QUERY 1
	Can distinguish between other errors and those resulting from a unique key violation.

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 query_ctx)
	Retrieve errors from the last query operation.

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, trunk_t trunk, char const *query_str, fr_sql_query_type_t type)
	Allocate an sql query structure.

unlang_action_t	rlm_sql_fetch_row (unlang_result_t p_result, request_t request, void *uctx)
	Call the driver's sql_fetch_row function.

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.

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

unlang_action_t	rlm_sql_trunk_query (unlang_result_t p_result, request_t request, void *uctx)
	Submit an SQL query using a trunk connection.

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

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

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.

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.

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

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: f60a9b1a6de7dcbc41f15941c42a17d67f348be0

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 152 of file rlm_sql.h.

Collaboration diagram for fr_sql_map_ctx_t:

Data Fields
TALLOC_CTX *	ctx	To allocate map entries in.
bool	expand_rhs	for reply items
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 136 of file rlm_sql.h.

Collaboration diagram for fr_sql_query_t:

Data Fields
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.
bool	expand_rhs	expand the RHS for check / reply tables
char const *	group_attribute	Name of the group attribute.
char const *	query_number_attribute	Name of the attribute to populate with the query number which succeeded when running a series of redundant queries.
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 196 of file rlm_sql.h.

Collaboration diagram for rlm_sql_escape_uctx_t:

Data Fields
rlm_sql_t const *	sql

◆ rlm_sql_thread_t

struct rlm_sql_thread_t

Definition at line 113 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 173 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 172 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 108 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 *query_ctx)

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]	query_ctx	to retrieve errors from.

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

Definition at line 194 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 126 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 119 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,
		trunk_t *	trunk,
		char const *	query_str,
		fr_sql_query_type_t	type
	)

Allocate an sql query structure.

Definition at line 183 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	(	unlang_result_t *	p_result,
		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.
request	Current request.
uctx	query context containing query to execute.

Returns: an unlang_action_t.

Definition at line 79 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 122 of file sql.c.

Here is the call graph for this function:

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 386 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	(	unlang_result_t *	p_result,
		request_t *	request,
		void *	uctx
	)

Submit an SQL query using a trunk connection.

Parameters

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

Returns: an unlang_action_t.

Definition at line 242 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	(	unlang_result_t *	p_result,
		request_t *	request,
		fr_sql_map_ctx_t *	map_ctx,
		trunk_t *	trunk
	)

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

Definition at line 356 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_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_log()

◆ rlm_sql_trunk_query()

◆ sql_get_map_list()

◆ 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