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 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	rlm_sql_config_t

struct	rlm_sql_driver_t

struct	rlm_sql_escape_uctx_t

struct	rlm_sql_handle_t

struct	sql_acct_section_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_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, rlm_sql_handle_t handle, rlm_sql_config_t const *config)
	Retrieve errors from the last query operation. More...

Enumerations
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
sql_rcode_t	rlm_sql_fetch_row (rlm_sql_row_t out, rlm_sql_t const inst, request_t request, rlm_sql_handle_t *handle)
	Call the driver's sql_fetch_row function. More...

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

sql_rcode_t	rlm_sql_query (rlm_sql_t const inst, request_t request, rlm_sql_handle_t *handle, char const query))
	Call the driver's sql_query method, reconnecting if necessary. More...

void	rlm_sql_query_log (rlm_sql_t const inst, request_t request, sql_acct_section_t const section, char const query))

sql_rcode_t	rlm_sql_select_query (rlm_sql_t const inst, request_t request, rlm_sql_handle_t *handle, char const query))
	Call the driver's sql_select_query method, reconnecting if necessary. More...

int	sql_get_map_list (TALLOC_CTX ctx, rlm_sql_t const inst, request_t request, rlm_sql_handle_t handle, map_list_t out, char const query, fr_dict_attr_t const list)

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

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

◆ rlm_sql_config_t

struct rlm_sql_config_t

Definition at line 88 of file rlm_sql.h.

Collaboration diagram for rlm_sql_config_t:

Data Fields
sql_acct_section_t	accounting
char const *	allowed_chars	Chars which done need escaping..
char const *	authorize_check_query	Query used get check VPs for a user.
char const *	authorize_group_check_query	Query used get check VPs for a group.
char const *	authorize_group_reply_query	Query used get reply VPs for a group.
char const *	authorize_reply_query	Query used get reply VPs for a user.
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.
char const *	groupmemb_query	Query to determine group membership.
char const *	logfile	Keep a log of all SQL queries executed Useful for batch insertion with the NULL drivers.
sql_acct_section_t	postauth
fr_time_delta_t	query_timeout	How long to allow queries to run for.
char const *	query_user	xlat expansion used to specify the user to use as the subject of queries.
bool	read_groups	Read user groups by default. If false, Fall-Through = yes is required in the previous reply list to process groups.
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.

◆ rlm_sql_escape_uctx_t

struct rlm_sql_escape_uctx_t

Definition at line 177 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 135 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_row_t	row	Row data from the last query.

◆ sql_acct_section_t

struct sql_acct_section_t

Definition at line 75 of file rlm_sql.h.

Collaboration diagram for sql_acct_section_t:

Data Fields
CONF_SECTION *	cs	The CONF_SECTION representing the group of queries to process.
char const *	logfile
char const **	query
char const *	reference	Reference string, expanded to point to a group of queries.
bool	reference_cp

◆ sql_log_entry_t

struct sql_log_entry_t

Definition at line 59 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 65 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 35 of file rlm_sql.h.

◆ FR_ITEM_REPLY

#define FR_ITEM_REPLY 1

Definition at line 36 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 152 of file rlm_sql.h.

Typedef Documentation

◆ rlm_sql_row_t

typedef char** rlm_sql_row_t

Definition at line 57 of file rlm_sql.h.

◆ rlm_sql_t

typedef struct sql_inst rlm_sql_t

Definition at line 57 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, rlm_sql_handle_t *handle, rlm_sql_config_t const *config)

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

Enumeration Type Documentation

◆ sql_fall_through_t

enum sql_fall_through_t

Enumerator
FALL_THROUGH_NO
FALL_THROUGH_YES
FALL_THROUGH_DEFAULT

Definition at line 51 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 42 of file rlm_sql.h.

Function Documentation

◆ rlm_sql_fetch_row()

sql_rcode_t rlm_sql_fetch_row	(	rlm_sql_row_t *	out,
		rlm_sql_t const *	inst,
		request_t *	request,
		rlm_sql_handle_t **	handle
	)

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 (*handle)->row.

Parameters

out	Where to write row data.
inst	Instance of rlm_sql_t.
request	The Current request, may be NULL.
handle	Handle to retrieve errors for.

Returns

RLM_SQL_OK on success.
other sql_rcode_t constants on error.

Definition at line 299 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,
		rlm_sql_handle_t *	handle,
		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.
handle	Handle to retrieve errors for.
force_debug	Force all errors to be logged as debug messages.

Definition at line 337 of file sql.c.

Here is the caller graph for this function:

◆ rlm_sql_query()

sql_rcode_t rlm_sql_query	(	rlm_sql_t const *	inst,
		request_t *	request,
		rlm_sql_handle_t **	handle,
		char const *	query
	)

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

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

Parameters

handle	to query the database with. *handle should not be NULL, as this indicates previous reconnection attempt has failed.
request	Current request.
inst	rlm_sql_t instance data.
query	to execute. Should not be zero length.

Returns

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

Definition at line 392 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,
		request_t *	request,
		sql_acct_section_t const *	section,
		char const *	query
	)

Definition at line 613 of file sql.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rlm_sql_select_query()

sql_rcode_t rlm_sql_select_query	(	rlm_sql_t const *	inst,
		request_t *	request,
		rlm_sql_handle_t **	handle,
		char const *	query
	)

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.

Parameters

inst	rlm_sql_t instance data.
request	Current request.
handle	to query the database with. *handle should not be NULL, as this indicates previous reconnection attempt has failed.
query	to execute. Should not be zero length.

Returns

RLM_SQL_OK on success.
RLM_SQL_RECONNECT if a new handle is required (also sets *handle = NULL).
RLM_SQL_QUERY_INVALID, RLM_SQL_ERROR on invalid query or connection error.

Definition at line 493 of file sql.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sql_get_map_list()

int sql_get_map_list	(	TALLOC_CTX *	ctx,
		rlm_sql_t const *	inst,
		request_t *	request,
		rlm_sql_handle_t **	handle,
		map_list_t *	out,
		char const *	query,
		fr_dict_attr_t const *	list
	)

Definition at line 559 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

◆ rlm_sql_config_t

◆ rlm_sql_escape_uctx_t

◆ rlm_sql_handle_t

◆ sql_acct_section_t

◆ sql_log_entry_t

◆ sql_state_entry_t

Macro Definition Documentation

◆ FR_ITEM_CHECK

◆ FR_ITEM_REPLY

◆ RLM_SQL_RCODE_FLAGS_ALT_QUERY

Typedef Documentation

◆ rlm_sql_row_t

◆ rlm_sql_t

◆ sql_error_t

Enumeration Type Documentation

◆ sql_fall_through_t

◆ sql_rcode_t

Function Documentation

◆ rlm_sql_fetch_row()

◆ rlm_sql_print_error()

◆ rlm_sql_query()

◆ rlm_sql_query_log()

◆ rlm_sql_select_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