Detailed Description

Internals.

Structs
struct	ngx_http_51D_ipi_data_to_set
	Structure containing details of a specific header to be set as per the config file. More...
struct	ngx_http_51D_ipi_match_conf_t
	Match config structure set from the config file. More...
struct	ngx_http_51D_ipi_loc_conf_t
	Module location config. More...
struct	ngx_http_51D_ipi_main_conf_t
	Module main config. More...
struct	ngx_http_51D_ipi_srv_conf_t
	Module server config. More...

Macros
#define	FIFTYONE_DEGREES_IPI_PROPERTY_NOT_AVAILABLE "NoMatch"
	Default property value if it is not available or no match is found.
#define	FIFTYONE_DEGREES_IPI_VALUE_SEPARATOR (u_char*) ","
	Default separator.
#define	FIFTYONE_DEGREES_IPI_MAX_STRING 20000
	Maximum value string being returned.
#define	FIFTYONE_DEGREES_IPI_MAX_PROPS_STRING 2048
	Maximum size of string holding the full properties list.
#define	FIFTYONE_DEGREES_IPI_MEMORY_ADJUSTMENT 1.1
	NGINX shared memory zone requires minimum of 8 bytes and allocated size has to be power of 2.
#define	FIFTYONE_DEGREES_IPI_CONFIG_LEVELS 3
	3 Config levels main, server and location.

Functions
static void *	ngx_http_51D_ipi_create_main_conf (ngx_conf_t *cf)
	Create main config.
static void *	ngx_http_51D_ipi_create_srv_conf (ngx_conf_t *cf)
	Create server config.
static void *	ngx_http_51D_ipi_create_loc_conf (ngx_conf_t *cf)
	Create location config.
static char *	ngx_http_51D_ipi_merge_loc_conf (ngx_conf_t cf, void parent, void *child)
	Merge location config.
static char *	ngx_http_51D_ipi_merge_srv_conf (ngx_conf_t cf, void parent, void *child)
	Merge server config.
static char *	ngx_http_51D_ipi_set_loc (ngx_conf_t cf, ngx_command_t cmd, void *conf)
	Set function.
static char *	ngx_http_51D_ipi_set_srv (ngx_conf_t cf, ngx_command_t cmd, void *conf)
	Set function.
static char *	ngx_http_51D_ipi_set_main (ngx_conf_t cf, ngx_command_t cmd, void *conf)
	Set function.
static ngx_int_t	ngx_http_51D_ipi_handler (ngx_http_request_t *r)
	Module handler, gets a match using the client IP address, or an IP address held in the variable specified by the directive, then sets the requested properties as request headers.
static ngx_int_t	ngx_http_51D_ipi_init_shm_resource_manager (ngx_shm_zone_t shm_zone, void data)
	Forward declaration of ngx_http_51D_ipi_init_shm_resource_manager.
static ngx_int_t	report_status (ngx_log_t log, StatusCode status, const char fileName)
	Report the status code returned by one of the 51Degrees APIs.
static ngx_int_t	report_insufficient_memory_status (ngx_log_t *log)
	Report the insufficient memory since memory allocation is a common activity.
static ConfigIpi	get_config_ipi (ngx_http_51D_ipi_main_conf_t *fdmcf)
	Get a fiftyoneDegreesConfigIpi instance based on the main configuration.
static PropertiesRequired	get_properties_ipi (ngx_http_51D_ipi_main_conf_t *fdmcf)
	Get the required properties to initialise the engine with.
static ngx_int_t	ngx_http_51D_ipi_post_conf (ngx_conf_t *cf)
	Module post config.
static void	ngx_http_51D_ipi_init_match_conf (ngx_http_51D_ipi_match_conf_t *matchConf)
	Initialises the match config so no headers are set.
static void *	ngx_http_51D_ipi_shm_alloc (size_t __size)
	Shared memory alloc function.
static void *	ngx_http_51D_ipi_shm_alloc_aligned (int alignment, size_t __size)
	Shared memory alloc aligned function.
static void	ngx_http_51D_ipi_shm_free (void *__ptr)
	Shared memory free function.
static ngx_int_t	ngx_http_51D_ipi_init_module (ngx_cycle_t *cycle)
	Init module function.
static ngx_int_t	ngx_http_51D_ipi_init_process (ngx_cycle_t *cycle)
	Init process function.
static void	ngx_http_51D_ipi_exit_process (ngx_cycle_t *cycle)
	Exit process function.
static void	ngx_http_51D_ipi_exit_master (ngx_cycle_t *cycle)
	Exit master process.
static void	add_value (char delimiter, char val, char *dst, size_t length)
	Add value function.
static ngx_str_t *	empty_string (ngx_http_request_t *r)
	Create an empty ngx string from the http request pool.
static ngx_str_t *	copy_string_null_terminated (ngx_http_request_t r, ngx_str_t str)
	Take a null terminated copy of an nginx string.
static ngx_str_t *	get_evidence_from_variable (ngx_http_request_t r, ngx_str_t variableName)
	Search and get the value of an nginx variable, unescaping any URI encoding.
static ngx_uint_t	ngx_http_51D_ipi_get_match (ngx_http_51D_ipi_main_conf_t fdmcf, ngx_http_request_t r, ngx_str_t *ipAddress)
	Get match function.
static void	ngx_http_51D_ipi_get_value (ngx_http_51D_ipi_main_conf_t fdmcf, ngx_http_request_t r, char values_string, const char requiredPropertyName, size_t length)
	Get value function.
static u_char *	getEscapedMatchedValueString (ngx_http_request_t r, ngx_http_51D_ipi_main_conf_t fdmcf, ngx_http_51D_ipi_data_to_set header, int haveMatch, ngx_str_t ipAddress)
	Perform a match if required and return an escaped value string for the header to set.
static ngx_uint_t	process (ngx_http_request_t r, ngx_http_51D_ipi_main_conf_t fdmcf, ngx_http_51D_ipi_data_to_set header, int haveMatch, ngx_str_t ipAddress)
	Process a request by performing a match and setting the resulting property values as a request header.
static char *	set_data (ngx_conf_t cf, ngx_http_51D_ipi_data_to_set data, ngx_str_t value, ngx_http_51D_ipi_main_conf_t fdmcf)
	Set data function.
static char *	ngx_http_51D_ipi_set_conf_header (ngx_conf_t cf, ngx_command_t cmd, ngx_http_51D_ipi_match_conf_t *matchConf)
	Set function.

Variables
ngx_module_t	ngx_http_51D_ipi_module
	Global module declaration.
static ngx_shm_zone_t *	ngx_http_51D_ipi_shm_resource_manager
	Pointer to the shared memory zone for the resource manager.
static ngx_atomic_t	ngx_http_51D_ipi_shm_tag = 1
	Atomic integer used to ensure a new data set memory zone on each reload.
static ngx_atomic_t *	ngx_http_51D_ipi_worker_count
	Count number of current worker processes.
static ngx_command_t	ngx_http_51D_ipi_commands []
	Definitions of the directives which can be called from the config file.
static ngx_http_module_t	ngx_http_51D_ipi_module_ctx
	Module context.

Macro Definition Documentation

◆ FIFTYONE_DEGREES_IPI_MAX_STRING

#define FIFTYONE_DEGREES_IPI_MAX_STRING 20000

Maximum value string being returned.

Some properties such as Areas return large WKT strings, so allow a reasonably large buffer.

◆ FIFTYONE_DEGREES_IPI_MEMORY_ADJUSTMENT

#define FIFTYONE_DEGREES_IPI_MEMORY_ADJUSTMENT 1.1

NGINX shared memory zone requires minimum of 8 bytes and allocated size has to be power of 2.

Any non-conforming value will be rounded up. Thus make this adjustment value account for the extra rounded up memory.

Function Documentation

◆ add_value()

void add_value	(	char *	delimiter,
		char *	val,
		char *	dst,
		size_t	length )

static

Add value function.

Appends a string to a list separated by the delimiter specified with 51D_value_separator_ipi, or a comma by default. Values which do not fit in the remaining space are truncated.

Parameters

delimiter	to split values with.
val	the string to add to dst.
dst	the string to append the val to.
length	the space remaining in dst, including the null terminator.

◆ copy_string_null_terminated()

ngx_str_t * copy_string_null_terminated	(	ngx_http_request_t *	r,
		ngx_str_t *	str )

static

Take a null terminated copy of an nginx string.

The IP address parser in the engine reads one byte beyond the characters provided, so a string which is not null terminated, such as the connection address text, must be copied before being used for a match.

Parameters

r	the nginx http request
str	the string to copy

Returns: the null terminated copy, or NULL if memory could not be allocated

◆ empty_string()

ngx_str_t * empty_string

(

ngx_http_request_t *

r

)

static

Create an empty ngx string from the http request pool.

Parameters

r	pointer to a http request

Returns: pointer to an empty ngx string

◆ get_config_ipi()

ConfigIpi get_config_ipi

(

ngx_http_51D_ipi_main_conf_t *

fdmcf

)

static

Get a fiftyoneDegreesConfigIpi instance based on the main configuration.

Only the in memory performance profile is supported as the data set is held in shared memory.

Parameters

fdmcf main configuration

Returns: fiftyoneDegreesConfigIpi instance

◆ get_evidence_from_variable()

ngx_str_t * get_evidence_from_variable	(	ngx_http_request_t *	r,
		ngx_str_t *	variableName )

static

Search and get the value of an nginx variable, unescaping any URI encoding.

Used to obtain the IP address when a variable is specified with a 51D_match_ipi directive.

Parameters

r	the nginx http request
variableName	the variable name to search for

Returns: the value of the variable, or an empty string if not found

◆ get_properties_ipi()

PropertiesRequired get_properties_ipi

(

ngx_http_51D_ipi_main_conf_t *

fdmcf

)

static

Get the required properties to initialise the engine with.

Where one or more 51D_match_ipi directives are present, only the properties they reference are required. Otherwise all properties in the data file are used.

Parameters

fdmcf main configuration

Returns: fiftyoneDegreesPropertiesRequired instance

◆ getEscapedMatchedValueString()

u_char * getEscapedMatchedValueString	(	ngx_http_request_t *	r,
		ngx_http_51D_ipi_main_conf_t *	fdmcf,
		ngx_http_51D_ipi_data_to_set *	header,
		int	haveMatch,
		ngx_str_t *	ipAddress )

static

Perform a match if required and return an escaped value string for the header to set.

Parameters

r	a ngx_http_request_t.
fdmcf	a main config object.
header	a header to construct a value string for.
haveMatch	whether a match has already been performed for the input IP address.
ipAddress	an IP address string to perform the match on.

Returns: an escaped value string. NULL if an error occurred.

◆ ngx_http_51D_ipi_create_loc_conf()

void * ngx_http_51D_ipi_create_loc_conf

(

ngx_conf_t *

cf

)

static

Create location config.

Allocates memory to the configuration.

Parameters

cf	nginx config.

Returns: Pointer to module location config.

◆ ngx_http_51D_ipi_create_main_conf()

void * ngx_http_51D_ipi_create_main_conf

(

ngx_conf_t *

cf

)

static

Create main config.

Allocates memory to the configuration and initialises config options to -1 (unset).

Parameters

cf	nginx config.

Returns: Pointer to module main config.

◆ ngx_http_51D_ipi_create_srv_conf()

void * ngx_http_51D_ipi_create_srv_conf

(

ngx_conf_t *

cf

)

static

Create server config.

Allocates memory to the configuration.

Parameters

cf	nginx config.

Returns: Pointer to the server config.

◆ ngx_http_51D_ipi_exit_master()

void ngx_http_51D_ipi_exit_master

(

ngx_cycle_t *

cycle

)

static

Exit master process.

Frees resources created for the module.

Parameters

cycle the current nginx cycle.

◆ ngx_http_51D_ipi_exit_process()

void ngx_http_51D_ipi_exit_process

(

ngx_cycle_t *

cycle

)

static

Exit process function.

Frees the results instance that was created on process init.

Parameters

cycle the current nginx cycle.

◆ ngx_http_51D_ipi_get_match()

ngx_uint_t ngx_http_51D_ipi_get_match	(	ngx_http_51D_ipi_main_conf_t *	fdmcf,
		ngx_http_request_t *	r,
		ngx_str_t *	ipAddress )

static

Get match function.

Performs an IP intelligence match for the IP address provided.

Parameters

fdmcf	module main config.
r	the current HTTP request.
ipAddress	the IP address to perform the match on.

Returns: Nginx status code.

◆ ngx_http_51D_ipi_get_value()

void ngx_http_51D_ipi_get_value	(	ngx_http_51D_ipi_main_conf_t *	fdmcf,
		ngx_http_request_t *	r,
		char *	values_string,
		const char *	requiredPropertyName,
		size_t	length )

static

Get value function.

Gets the requested value for the current match and appends the value to the list of values separated by the delimiter specified with 51D_value_separator_ipi.

Parameters

fdmcf	module main config.
r	the current HTTP request.
values_string	the string to append the returned value to.
requiredPropertyName	the name of the property to get the value for.
length	the size allocated to the values_string variable.

◆ ngx_http_51D_ipi_handler()

ngx_int_t ngx_http_51D_ipi_handler

(

ngx_http_request_t *

r

)

static

Module handler, gets a match using the client IP address, or an IP address held in the variable specified by the directive, then sets the requested properties as request headers.

Parameters

r	the HTTP request.

Returns: ngx_int_t nginx status.

◆ ngx_http_51D_ipi_init_match_conf()

void ngx_http_51D_ipi_init_match_conf

(

ngx_http_51D_ipi_match_conf_t *

matchConf

)

static

Initialises the match config so no headers are set.

Parameters

matchConf to initialise.

◆ ngx_http_51D_ipi_init_module()

ngx_int_t ngx_http_51D_ipi_init_module

(

ngx_cycle_t *

cycle

)

static

Init module function.

Initialises the resource manager with the given initialisation parameters. Throws an error if the resource manager could not be initialised.

Parameters

cycle the current nginx cycle.

Returns: ngx_int_t nginx conf status.

◆ ngx_http_51D_ipi_init_process()

ngx_int_t ngx_http_51D_ipi_init_process

(

ngx_cycle_t *

cycle

)

static

Init process function.

Creates a results instance from the shared resource manager. This results instance is local to the process.

Parameters

cycle the current nginx cycle.

Returns: ngx_int_t nginx status.

◆ ngx_http_51D_ipi_init_shm_resource_manager()

ngx_int_t ngx_http_51D_ipi_init_shm_resource_manager	(	ngx_shm_zone_t *	shm_zone,
		void *	data )

static

Forward declaration of ngx_http_51D_ipi_init_shm_resource_manager.

Init resource manager memory zone.

Allocates space for the resource manager in the shared memory zone.

Parameters

shm_zone	the shared memory zone.
data	if the zone has been carried over from a reload, this is the old data.

Returns: ngx_int_t nginx conf status.

◆ ngx_http_51D_ipi_merge_loc_conf()

char * ngx_http_51D_ipi_merge_loc_conf	(	ngx_conf_t *	cf,
		void *	parent,
		void *	child )

static

Merge location config.

Either gets the value of count that is set, or sets to the default of 0.

◆ ngx_http_51D_ipi_merge_srv_conf()

char * ngx_http_51D_ipi_merge_srv_conf	(	ngx_conf_t *	cf,
		void *	parent,
		void *	child )

static

Merge server config.

Either gets the value of count that is set, or sets to the default of 0.

◆ ngx_http_51D_ipi_post_conf()

ngx_int_t ngx_http_51D_ipi_post_conf

(

ngx_conf_t *

cf

)

static

Module post config.

Adds the module to the HTTP rewrite phase array, sets the defaults if necessary, and sets the shared memory zone used to hold the resource manager and data set.

Parameters

cf	nginx config.

Returns: ngx_int_t nginx conf status.

◆ ngx_http_51D_ipi_set_conf_header()

char * ngx_http_51D_ipi_set_conf_header	(	ngx_conf_t *	cf,
		ngx_command_t *	cmd,
		ngx_http_51D_ipi_match_conf_t *	matchConf )

static

Set function.

Is called for each occurrence of "51D_match_ipi". Allocates space for the header structure and initialises it with the set data function.

Parameters

cf	the nginx conf.
cmd	the name of the command called from the config file.
matchConf	the match config.

Returns: char* nginx conf status.

◆ ngx_http_51D_ipi_set_loc()

char * ngx_http_51D_ipi_set_loc	(	ngx_conf_t *	cf,
		ngx_command_t *	cmd,
		void *	conf )

static

Set function.

Is called for occurrences of "51D_match_ipi" in a location config block.

Parameters

cf	the nginx conf.
cmd	the name of the command called from the config file.
conf	A pointer to the context for configuration object

Returns: char* nginx conf status.

◆ ngx_http_51D_ipi_set_main()

char * ngx_http_51D_ipi_set_main	(	ngx_conf_t *	cf,
		ngx_command_t *	cmd,
		void *	conf )

static

Set function.

Is called for occurrences of "51D_match_ipi" in a http config block.

Parameters

cf	the nginx conf.
cmd	the name of the command called from the config file.
conf	A pointer to the context for configuration object

Returns: char* nginx conf status.

◆ ngx_http_51D_ipi_set_srv()

char * ngx_http_51D_ipi_set_srv	(	ngx_conf_t *	cf,
		ngx_command_t *	cmd,
		void *	conf )

static

Set function.

Is called for occurrences of "51D_match_ipi" in a server config block.

Parameters

cf	the nginx conf.
cmd	the name of the command called from the config file.
conf	A pointer to the context for configuration object

Returns: char* nginx conf status.

◆ ngx_http_51D_ipi_shm_alloc()

void * ngx_http_51D_ipi_shm_alloc

(

size_t

__size

)

static

Shared memory alloc function.

Replaces fiftyoneDegreesMalloc to store the data set in the shared memory zone.

Parameters

__size the size of memory to allocate.

Returns: void* a pointer to the allocated memory.

◆ ngx_http_51D_ipi_shm_alloc_aligned()

void * ngx_http_51D_ipi_shm_alloc_aligned	(	int	alignment,
		size_t	__size )

static

Shared memory alloc aligned function.

If the __size is not multiple of alignment, it will be rounded up. See the equivalent function in the device detection module for the reasoning behind using the standard shared memory alloc for aligned allocations.

Parameters

alignment	of the requested memory block
__size	to be allocated

Returns: pointer to the allocated memory

◆ ngx_http_51D_ipi_shm_free()

void ngx_http_51D_ipi_shm_free

(

void *

__ptr

)

static

Shared memory free function.

Replaces fiftyoneDegreesFree to free pointers to the shared memory zone.

Parameters

__ptr pointer to the memory to be freed.

◆ process()

ngx_uint_t process	(	ngx_http_request_t *	r,
		ngx_http_51D_ipi_main_conf_t *	fdmcf,
		ngx_http_51D_ipi_data_to_set *	header,
		int	haveMatch,
		ngx_str_t *	ipAddress )

static

Process a request by performing a match and setting the resulting property values as a request header.

Parameters

r	the http request
fdmcf	the main configuration of the module
header	the header to set
haveMatch	indicates if a match has already been performed for the input IP address
ipAddress	the IP address to perform the match for

Returns: code to indicate the status of the operation.

◆ report_insufficient_memory_status()

ngx_int_t report_insufficient_memory_status

(

ngx_log_t *

log

)

static

Report the insufficient memory since memory allocation is a common activity.

Parameters

log	the log to write the message to.

Returns: error

◆ report_status()

ngx_int_t report_status	(	ngx_log_t *	log,
		StatusCode	status,
		const char *	fileName )

static

Report the status code returned by one of the 51Degrees APIs.

Parameters

log	the log to write the error message to.
status	the status code returned by one of the 51Degrees APIs.
fileName	of the data file being used.

Returns: error

◆ set_data()

char * set_data	(	ngx_conf_t *	cf,
		ngx_http_51D_ipi_data_to_set *	data,
		ngx_str_t *	value,
		ngx_http_51D_ipi_main_conf_t *	fdmcf )

static

Set data function.

Initialises the data structure for a given occurrence of "51D_match_ipi" in the config file. Allocates space required and sets the name and properties.

Parameters

cf	the nginx config.
data	data to be set.
value	the values passed from the config file.
fdmcf	the module main config.

Returns: Nginx status code.

Variable Documentation

◆ ngx_http_51D_ipi_commands

ngx_command_t ngx_http_51D_ipi_commands[]

static

Definitions of the directives which can be called from the config file.

–51D_match_ipi takes two string arguments, the name of the header to be set and a comma separated list of properties to be returned. The third argument is optional to specify a variable holding an IP address to be used in place of the client IP address. Is called within main, server and location blocks. Enables IP intelligence matching. –51D_file_path_ipi takes one string argument, the path to a 51Degrees IP intelligence data file. Is called within the main block. –51D_value_separator_ipi takes one string argument, the separator of the values being returned.