51Degrees Device Detection Nginx  4.5

A device detection module for Nginx

Search

Documentation

51Degrees Device Detection Nginx Module

Detailed Description

Internals.

Structs
struct	ngx_http_51D_data_to_set
	Structure containing details of a specific header to be set as per the config file. More...
struct	ngx_http_51D_match_conf_t
	Match config structure set from the config file. More...
struct	ngx_http_51D_loc_conf_t
	Module location config. More...
struct	ngx_http_51D_main_conf_t
	Module main config. More...
struct	ngx_http_51D_srv_conf_t
	Module server config. More...

Macros
#define	FIFTYONE_DEGREES_DEFAULTFILE   (u_char*) "51Degrees-LiteV4.1.hash"
	Default data file to use.
#define	FIFTYONE_DEGREES_PROPERTY_NOT_AVAILABLE   "NoMatch"
	Default property value if it is not available or no match is found.
#define	FIFTYONE_DEGREES_JAVASCRIPT_NOT_AVAILABLE   "/* 51Degrees Javascript not available. */"
	Default Javascript content if it is not available or no match is found.
#define	FIFTYONE_DEGREES_VALUE_SEPARATOR   (u_char*) ","
	Default separator.
#define	FIFTYONE_DEGREES_MAX_STRING   20000
	Maximum value string being returned.
#define	FIFTYONE_DEGREES_MAX_PROPS_STRING   2048
	Maxium size of string hold full properties list.
#define	FIFTYONE_DEGREES_SET_HEADER_PREFIX   "SetHeader"
	The SetHeader prefix value.
#define	FIFTYONE_DEGREES_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_TRUE   1
	True constant.
#define	FIFTYONE_DEGREES_FALSE   0
	False constant.
#define	FIFTYONE_DEGREES_CONFIG_LEVELS   3
	3 Config levels main, server and location.

Typedefs
typedef enum ngx_http_51D_performance_profile_e	ngx_http_51D_performance_profile
	Performance profiles.
typedef ngx_uint_t	ngx_http_51D_multi_header_mode
	Multi-header detection mode.

Enumerations
enum	ngx_http_51D_performance_profile_e {   ngx_http_51D_profile_in_memory = 1 , ngx_http_51D_profile_high_performance , ngx_http_51D_profile_low_memory , ngx_http_51D_profile_balanced ,   ngx_http_51D_profile_balanced_temp }
	Performance profiles enumerator. More...
enum	ngx_http_51D_multi_mode_bits { ngx_http_51D_multi_mode_bit_ua_only = 0 , ngx_http_51D_multi_mode_bit_client_hints , ngx_http_51D_multi_mode_bit_all_evidence , ngx_http_51D_multi_mode_bits_count }
	Multi-header detection mode bits enumerator. More...
enum	ngx_http_51D_multi_mode_masks { ngx_http_51D_multi_mode_mask_ua_only = 1 << ngx_http_51D_multi_mode_bit_ua_only , ngx_http_51D_multi_mode_mask_client_hints = 1 << ngx_http_51D_multi_mode_bit_client_hints , ngx_http_51D_multi_mode_mask_all_evidence = 1 << ngx_http_51D_multi_mode_bit_all_evidence , ngx_http_51D_multi_mode_mask_non_ua_only = ((1 << ngx_http_51D_multi_mode_bits_count) - 1) & ~ngx_http_51D_multi_mode_mask_ua_only }
	Multi-header detection mode masks enumerator. More...

Functions
static void *	ngx_http_51D_create_main_conf (ngx_conf_t *cf)
	Forward declaration of ngx_http_51D_create_main_conf.
static void *	ngx_http_51D_create_srv_conf (ngx_conf_t *cf)
	Forward declaration of ngx_http_51D_create_srv_conf.
static void *	ngx_http_51D_create_loc_conf (ngx_conf_t *cf)
	Forward declaration of ngx_http_51D_create_loc_conf.
static char *	ngx_http_51D_merge_loc_conf (ngx_conf_t *cf, void *parent, void *child)
	Forward declaration of ngx_http_51D_merge_loc_conf.
static char *	ngx_http_51D_merge_srv_conf (ngx_conf_t *cf, void *parent, void *child)
	Forward declaration of ngx_http_51D_merge_srv_conf.
static char *	ngx_http_51D_set_loc_resp (ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
	Forward declaration of ngx_http_51D_set_loc_resp.
static char *	ngx_http_51D_set_srv_resp (ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
	Forward declaration of ngx_http_51D_set_srv_resp.
static char *	ngx_http_51D_set_main_resp (ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
	Forward declaration of ngx_http_51D_set_main_resp.
static char *	ngx_http_51D_set_loc_cdn (ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
	Forward declaration of ngx_http_51D_set_loc_cdn.
static char *	ngx_http_51D_set_loc (ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
	Forward declaration of ngx_http_51D_set_loc.
static char *	ngx_http_51D_set_srv (ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
	Forward declaration of ngx_http_51D_set_srv.
static char *	ngx_http_51D_set_main (ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
	Forward declaration of ngx_http_51D_set_main.
static ngx_int_t	ngx_http_51D_handler (ngx_http_request_t *r)
	Forward declaration of ngx_http_51D_handler.
static ngx_int_t	ngx_http_51D_header_filter (ngx_http_request_t *r)
	Forward declaration of ngx_http_51D_header_filter.
static ngx_int_t	ngx_http_51D_body_filter (ngx_http_request_t *r, ngx_chain_t *in)
	Forward declaration of ngx_http_51D_body_filter.
static ngx_int_t	ngx_http_51D_init_shm_resource_manager (ngx_shm_zone_t *shm_zone, void *data)
	Forward declaration of ngx_http_51D_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 ConfigHash	get_config_hash (ngx_http_51D_main_conf_t *fdmcf)
	Get a fiftyoneDegreesConfigHash instance based on the main configuration.
static PropertiesRequired	get_properties_hash (ngx_http_51D_main_conf_t *fdmcf)
	Get a fiftyoneDegreesPropertiesRequired instance restricted to the properties named in the configuration directives, which are accumulated in the main configuration.
static ngx_int_t	ngx_http_51D_post_conf (ngx_conf_t *cf)
	Module post config.
static void	ngx_http_51D_init_match_conf (ngx_http_51D_match_conf_t *matchConf)
	Initialises the match config so no headers and body are set.
void *	ngx_http_51D_shm_alloc (size_t __size)
	Shared memory alloc function.
void *	ngx_http_51D_shm_alloc_aligned (int alignment, size_t __size)
	Shared memory alloc aligned function.
void	ngx_http_51D_shm_free (void *__ptr)
	Shared memory free function.
static ngx_int_t	ngx_http_51D_init_module (ngx_cycle_t *cycle)
	Init module function.
static const char *	skipComponentName (const char *headerName)
	Skip the component name in the header and return the pointer to the response header name.
static ngx_int_t	getRespHeaderIndex (ngx_str_t *headerNames, const char *headerName, ngx_uint_t respHeaderCount)
	Get the header index of a given header name in the list of detected headers.
static ngx_http_51D_data_to_set *	getRespHeader (ngx_http_51D_data_to_set *respHeader, const char *headerName)
	Find a header name in a header to set linked list.
static ngx_int_t	initRespHeaders (ngx_cycle_t *cycle, ngx_http_51D_main_conf_t *fdmcf, DataSetHash *dataSet)
	Initialise the array of response headers to set.
static ngx_int_t	ngx_http_51D_init_process (ngx_cycle_t *cycle)
	Init process function.
void	ngx_http_51D_exit_process (ngx_cycle_t *cycle)
	Exit process function.
void	ngx_http_51D_exit_master (ngx_cycle_t *cycle)
	Exit master process.
static ngx_table_elt_t *	search_headers_in (ngx_http_request_t *r, u_char *name, size_t len)
	Search headers function.
static void	add_value (char *delimiter, char *val, char *dst, size_t length)
	Add value function.
static bool	is_metadata (char *val)
	Check if a property being requested is a meta data property.
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 *	get_evidence_from_query_string_base (ngx_http_request_t *r, ngx_str_t *variableName)
	Search and get the evidence from the query string.
static ngx_str_t *	get_evidence_from_query_string (ngx_http_request_t *r, ngx_str_t *variableName)
	Search and get the evidence from the query string.
static bool	has_cookie_value (ngx_http_request_t *r, ngx_str_t *s, ngx_str_t *cookie)
	Check whether there is a cookie with the name supplied.
static void	add_override_evidence_from_cookie_and_query (ngx_http_request_t *r, ResultsHash *results, EvidenceKeyValuePairArray *evidence)
	Add evidence required by the Hash device detection from cookie and query string.
static int	is_header_allowed_for_UA_UACH_mode (const char *const headerName)
static EvidenceKeyValuePairArray *	get_evidence (ResultsHash *results, ngx_http_request_t *r, ngx_http_51D_multi_header_mode multiMode)
	Create an evidence array and added the evidence from the http request.
static ngx_uint_t	ngx_http_51D_get_match (ngx_http_51D_main_conf_t *fdmcf, ngx_http_request_t *r, ngx_http_51D_multi_header_mode multi, ngx_str_t *userAgent)
	Get match function.
static void	removeUnknown (char *dest, ngx_int_t *charsAdded)
	Remove Unknown string from a given string and updated the number of characers added with 'Unknown' being removed.
void	ngx_http_51D_get_value (ngx_http_51D_main_conf_t *fdmcf, ngx_http_request_t *r, char *values_string, const char *requiredPropertyName, size_t length, ngx_uint_t includeNotAvailable, const char *customSeparator)
	Get value function.
static ngx_str_t *	ngx_http_51D_get_user_agent (ngx_http_request_t *r, ngx_http_51D_data_to_set *data)
	Get the user agent using the header name specified by the user in the configuration.
u_char *	getEscapedMatchedValueString (ngx_http_request_t *r, ngx_http_51D_main_conf_t *fdmcf, ngx_http_51D_data_to_set *header, int haveMatch, ngx_uint_t includeNotAvailable, ngx_str_t *userAgent, const char *customSeparator)
	Perform detection if required and returned an escaped value string for the header to set.
ngx_uint_t	process (ngx_http_request_t *r, ngx_http_51D_main_conf_t *fdmcf, ngx_http_51D_data_to_set *header, ngx_table_elt_t *h[], int matchIndex, int haveMatch, ngx_str_t *userAgent)
	Process a request and perform device detection based on the request info.
static ngx_table_elt_t *	findResponseHeader (ngx_http_request_t *r, ngx_str_t headerName)
	Find a header in the response header list.
static char *	set_data (ngx_conf_t *cf, ngx_http_51D_data_to_set *data, ngx_str_t *value, char *propertiesString, int propertiesCount, ngx_http_51D_main_conf_t *fdmcf)
	Set data function.
static char *	ngx_http_51D_set_header (ngx_conf_t *cf, ngx_http_51D_data_to_set *header, ngx_str_t *value, ngx_http_51D_main_conf_t *fdmcf)
	Set up the header to be set.
static char *	ngx_http_51D_set_body (ngx_conf_t *cf, ngx_http_51D_data_to_set *body, ngx_str_t *value, ngx_http_51D_main_conf_t *fdmcf)
	Set up the body to be set.
static char *	ngx_http_51D_set_conf_header (ngx_conf_t *cf, ngx_command_t *cmd, ngx_http_51D_match_conf_t *matchConf)
	Set function.
static char *	ngx_http_51D_set_conf_body (ngx_conf_t *cf, ngx_command_t *cmd, ngx_http_51D_match_conf_t *matchConf)
	Set function.
static char *	ngx_http_51D_set_conf_resp (ngx_conf_t *cf, ngx_command_t *cmd, ngx_http_51D_match_conf_t *matchConf)
	Set function.

Variables
ngx_module_t	ngx_http_51D_module
	Global module declaration.
static ngx_http_output_header_filter_pt	ngx_http_next_header_filter
	Declaration of the next header filter function pointer.
static ngx_http_output_body_filter_pt	ngx_http_next_body_filter
	Declaration of the next body filter function pointer.
static ngx_shm_zone_t *	ngx_http_51D_shm_resource_manager
	Pointer to shared memory zones.
ngx_atomic_t	ngx_http_51D_shm_tag = 1
	Atomic integer used to ensure a new data set memory zone on each reload.
ngx_atomic_t *	ngx_http_51D_worker_count
	Count number of current worker processes.
static const char *const	NGX_HTTP_51D_HEADER_PREFIX_CLIENT_HINT = "Sec-CH-UA-"
static const char *const	NGX_HTTP_51D_HEADER_USER_AGENT = "User-Agent"
static ngx_conf_enum_t	ngx_http_51D_performance_profiles []
	Performance profile map, to map user specified string with corresponding profile.
static ngx_command_t	ngx_http_51D_commands []
	Definitions of functions which can be called from the config file.
static ngx_http_module_t	ngx_http_51D_module_ctx
	Module context.

Macro Definition Documentation

◆ FIFTYONE_DEGREES_MAX_STRING

#define FIFTYONE_DEGREES_MAX_STRING   20000

Maximum value string being returned.

The biggest Javascript is 11666 so choose a number that is reasonably bigger than as as max length

◆ FIFTYONE_DEGREES_MEMORY_ADJUSTMENT

#define FIFTYONE_DEGREES_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.

Typedef Documentation

◆ ngx_http_51D_multi_header_mode

typedef ngx_uint_t ngx_http_51D_multi_header_mode

Multi-header detection mode.

See ngx_http_51D_multi_mode_bits and ngx_http_51D_multi_mode_masks below.

Enumeration Type Documentation

◆ ngx_http_51D_multi_mode_bits

enum ngx_http_51D_multi_mode_bits

Multi-header detection mode bits enumerator.

Describes bit flag meanings for ngx_http_51D_multi_header_mode.

◆ ngx_http_51D_multi_mode_masks

enum ngx_http_51D_multi_mode_masks

Multi-header detection mode masks enumerator.

Describes bit flag combination meanings for ngx_http_51D_multi_header_mode.

◆ ngx_http_51D_performance_profile_e

enum ngx_http_51D_performance_profile_e

Performance profiles enumerator.

NOTE: Only in_memory is currently supported.

Function Documentation

◆ add_override_evidence_from_cookie_and_query()

void add_override_evidence_from_cookie_and_query ( ngx_http_request_t * r, ResultsHash * results, EvidenceKeyValuePairArray * evidence )

static

Add evidence required by the Hash device detection from cookie and query string.

Parameters

r	pointer to a http request
results	pointers to results hash instance
evidence	pointer to the evidence collection
cookies	pointer to the array of cookies

◆ 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_valueSeparator, 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.

◆ 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

◆ findResponseHeader()

ngx_table_elt_t * findResponseHeader ( ngx_http_request_t * r, ngx_str_t headerName )

static

Find a header in the response header list.

Parameters

r	a ngx_http_request_t
headerName	header name to find.

Returns

pointer to the header that match.

◆ get_config_hash()

ConfigHash get_config_hash ( ngx_http_51D_main_conf_t * fdmcf )

static

Get a fiftyoneDegreesConfigHash instance based on the main configuration.

Parameters

fdmcf

main configuration

Returns

fiftyoneDegreesConfigHash instance

◆ get_evidence()

EvidenceKeyValuePairArray * get_evidence ( ResultsHash * results, ngx_http_request_t * r, ngx_http_51D_multi_header_mode multiMode )

static

Create an evidence array and added the evidence from the http request.

This should consider the evidence sent from cookies and query, since overrides are required by customer. This requires parsing the query string for the override values. For MVP might consider the override from cookies only.

Parameters

results	the results to hold the return value of the detection
r	the http request that contains the evidence
multiMode	describes which headers to use for evidence.

Returns

an array of evidence

◆ get_evidence_from_query_string()

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

static

Search and get the evidence from the query string.

If the variable does not contains 'arg_' prefix, add it as this is required by nginx.

Parameters

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

Returns

the evidence

◆ get_evidence_from_query_string_base()

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

static

Search and get the evidence from the query string.

Parameters

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

Returns

the evidence

◆ get_properties_hash()

PropertiesRequired get_properties_hash ( ngx_http_51D_main_conf_t * fdmcf )

static

Get a fiftyoneDegreesPropertiesRequired instance restricted to the properties named in the configuration directives, which are accumulated in the main configuration.

Detection only evaluates the components which the required properties belong to, so initialising the data set with all of its properties makes every match considerably more expensive. All of the data file's properties are initialised when no data set properties are named, or when response headers are enabled, as the SetHeader properties used by 51D_set_resp_headers are discovered from the data file rather than named in directives.

Parameters

fdmcf

main configuration

Returns

fiftyoneDegreesPropertiesRequired instance

◆ getEscapedMatchedValueString()

u_char * getEscapedMatchedValueString	(	ngx_http_request_t *	r,
		ngx_http_51D_main_conf_t *	fdmcf,
		ngx_http_51D_data_to_set *	header,
		int	haveMatch,
		ngx_uint_t	includeNotAvailable,
		ngx_str_t *	userAgent,
		const char *	customSeparator )

Perform detection if required and returned 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 value string for.
haveMatch	whether a match has already been perfomed for the input User-Agents.
includeNotAvailable	whether not available property (e.g. 'Unknown' or hasValues=false) should be included in the value string.
userAgent	a User-Agent string to perform the match on.
customSeparator	custom separator to be used instead of the 51D_value_separator. @ return an escaped value string. NULL if error occurred.

◆ getRespHeader()

ngx_http_51D_data_to_set * getRespHeader ( ngx_http_51D_data_to_set * respHeader, const char * headerName )

static

Find a header name in a header to set linked list.

Parameters

respHeader	pointer to the first element in a list
headerName	a header to search for.

Returns

pointer to the element that match. NULL if not found.

◆ getRespHeaderIndex()

ngx_int_t getRespHeaderIndex ( ngx_str_t * headerNames, const char * headerName, ngx_uint_t respHeaderCount )

static

Get the header index of a given header name in the list of detected headers.

Parameters

headerNames	list of detected headers.
headerName	a header name to search for.
respHeaderCount	the number of detected headers.

Returns

index of the input header. -1 if not found.

◆ has_cookie_value()

bool has_cookie_value ( ngx_http_request_t * r, ngx_str_t * s, ngx_str_t * cookie )

static

Check whether there is a cookie with the name supplied.

Parameters

r	pointer to a http request
s	name of the cookie to look for
cookie	pointer to an ngx_str_t to write the value to

Returns

true if the cookie was found

◆ initRespHeaders()

ngx_int_t initRespHeaders ( ngx_cycle_t * cycle, ngx_http_51D_main_conf_t * fdmcf, DataSetHash * dataSet )

static

Initialise the array of response headers to set.

Parameters

cycle	pointer to the current cycle.
fdmcf	pointer to the 51Degrees main config object.
dataSet	pointer to the 51Degrees Hash dataset.

Returns

status.

◆ is_metadata()

bool is_metadata ( char * val )

static

Check if a property being requested is a meta data property.

Parameters

val	the string value.

◆ ngx_http_51D_body_filter()

ngx_int_t ngx_http_51D_body_filter ( ngx_http_request_t * r, ngx_chain_t * in )

static

Forward declaration of ngx_http_51D_body_filter.

Body filter of the response.

This is called first in the body filter chain. It then call the subsequent filter in the chain with the updated response and either old or new content, depending on whether a matching is successfully performed.

Parameters

r	the response.
in	the body chain.

Returns

the status code.

◆ ngx_http_51D_create_loc_conf()

void * ngx_http_51D_create_loc_conf ( ngx_conf_t * cf )

static

Forward declaration of ngx_http_51D_create_loc_conf.

Create location config.

Allocates memory to the configuration.

Parameters

cf	nginx config.

Returns

Pointer to module location config.

◆ ngx_http_51D_create_main_conf()

void * ngx_http_51D_create_main_conf ( ngx_conf_t * cf )

static

Forward declaration of ngx_http_51D_create_main_conf.

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_create_srv_conf()

void * ngx_http_51D_create_srv_conf ( ngx_conf_t * cf )

static

Forward declaration of ngx_http_51D_create_srv_conf.

Create server config.

Allocates memory to the configuration.

Parameters

cf	nginx config.

Returns

Pointer to the server config.

◆ ngx_http_51D_exit_master()

void ngx_http_51D_exit_master

(

ngx_cycle_t *

cycle

)

Exit master process.

Frees resource created for the 51Degrees module.

Parameters

cycle

the current nginx cycle.

◆ ngx_http_51D_exit_process()

void ngx_http_51D_exit_process

(

ngx_cycle_t *

cycle

)

Exit process function.

Frees the results set that was created on process init.

Parameters

cycle

the current nginx cycle.

◆ ngx_http_51D_get_match()

ngx_uint_t ngx_http_51D_get_match ( ngx_http_51D_main_conf_t * fdmcf, ngx_http_request_t * r, ngx_http_51D_multi_header_mode multi, ngx_str_t * userAgent )

static

Get match function.

Gets a match for either a single User-Agent or all request headers.

Parameters

fdmcf	module main config.
r	the current HTTP request.
multi	Bit mask: what headers to use.
userAgent	pointer to the user agent to perform the match on.

Returns

Nginx status code.

◆ ngx_http_51D_get_user_agent()

ngx_str_t * ngx_http_51D_get_user_agent ( ngx_http_request_t * r, ngx_http_51D_data_to_set * data )

static

Get the user agent using the header name specified by the user in the configuration.

This is only applied to the single match.

◆ ngx_http_51D_get_value()

void ngx_http_51D_get_value	(	ngx_http_51D_main_conf_t *	fdmcf,
		ngx_http_request_t *	r,
		char *	values_string,
		const char *	requiredPropertyName,
		size_t	length,
		ngx_uint_t	includeNotAvailable,
		const char *	customSeparator )

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

Parameters

fdmcf	51Degrees 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.
includeNotAvailable	whether or not, property whose hasValues=false or value is 'Unknown' should be included as part of the valuesString. In all cases whether properties are required by "51D_match_*" directives, this has to be 1 so that the values returned match the number of property required. Where this is called by "51D_set_resp_headers", this is not required since they won't be valid.
customSeparator	a separator to use instead of the 51D_value_separator. This is normally used for internal construction of string such as Client Hints response headers list where separator has to be ','.

◆ ngx_http_51D_handler()

ngx_int_t ngx_http_51D_handler ( ngx_http_request_t * r )

static

Forward declaration of ngx_http_51D_handler.

Module handler, gets a match using either the User-Agent or multiple http headers, then sets properties as headers.

This will call the 'process' method.

Parameters

r	the HTTP request.

Returns

ngx_int_t nginx status.

◆ ngx_http_51D_header_filter()

ngx_int_t ngx_http_51D_header_filter ( ngx_http_request_t * r )

static

Forward declaration of ngx_http_51D_header_filter.

Header filter for response message.

This is called first in the header filter change. It then call subsequent filter in the chain with the updated response.

Parameters

r	the response.

Returns

the status code.

◆ ngx_http_51D_init_match_conf()

void ngx_http_51D_init_match_conf ( ngx_http_51D_match_conf_t * matchConf )

static

Initialises the match config so no headers and body are set.

Parameters

matchConf

to initialise.

◆ ngx_http_51D_init_module()

ngx_int_t ngx_http_51D_init_module ( ngx_cycle_t * cycle )

static

Init module function.

Initialises the resrouce 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_init_process()

ngx_int_t ngx_http_51D_init_process ( ngx_cycle_t * cycle )

static

Init process function.

Creates a result set from the shared resource manager. This result set is local to the process. Here is where the ResultsHash will be initialised.

Parameters

cycle

the current nginx cycle.

Returns

ngx_int_t nginx status.

◆ ngx_http_51D_init_shm_resource_manager()

ngx_int_t ngx_http_51D_init_shm_resource_manager ( ngx_shm_zone_t * shm_zone, void * data )

static

Forward declaration of ngx_http_51D_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_merge_loc_conf()

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

static

Forward declaration of ngx_http_51D_merge_loc_conf.

Merge location config.

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

◆ ngx_http_51D_merge_srv_conf()

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

static

Forward declaration of ngx_http_51D_merge_srv_conf.

Merge server config.

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

◆ ngx_http_51D_post_conf()

ngx_int_t ngx_http_51D_post_conf ( ngx_conf_t * cf )

static

Module post config.

Adds the module to the HTTP access phase array, sets the defaults if necessary, and sets the shared memory zones. Added header and body filter to the filter chain for develiring Javascript content upon requests.

This will initialise the main configuration data, including the performanceProfile, drift, difference ...

Parameters

cf	nginx config.

Returns

ngx_int_t nginx conf status.

◆ ngx_http_51D_set_body()

char * ngx_http_51D_set_body ( ngx_conf_t * cf, ngx_http_51D_data_to_set * body, ngx_str_t * value, ngx_http_51D_main_conf_t * fdmcf )

static

Set up the body to be set.

Parameters

cf	the nginx config.
body	to be set.
value	the value that is passed from the config file.
fdmcf	the 51Degrees main config.

Returns

the status code

◆ ngx_http_51D_set_conf_body()

char * ngx_http_51D_set_conf_body ( ngx_conf_t * cf, ngx_command_t * cmd, ngx_http_51D_match_conf_t * matchConf )

static

Set function.

Is called for each occurrence of "51D_get_javascript_single" or "51D_get_javascript_all". Allocates space for the body structure and initialises it with the set body 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_set_conf_header()

char * ngx_http_51D_set_conf_header ( ngx_conf_t * cf, ngx_command_t * cmd, ngx_http_51D_match_conf_t * matchConf )

static

Set function.

Is called for each occurrence of "51D_match_single", "51D_match_ua", "51D_match_ua_client_hints" or "51D_match_all". Allocates space for the header structure and initialises it with the set header 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_set_conf_resp()

char * ngx_http_51D_set_conf_resp ( ngx_conf_t * cf, ngx_command_t * cmd, ngx_http_51D_match_conf_t * matchConf )

static

Set function.

Is called for each occurrence of "51D_set_resp_headers" Allocates space for the body structure and initialises it with the set body 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_set_header()

char * ngx_http_51D_set_header ( ngx_conf_t * cf, ngx_http_51D_data_to_set * header, ngx_str_t * value, ngx_http_51D_main_conf_t * fdmcf )

static

Set up the header to be set.

Parameters

cf	the nginx config.
header	the header to be set.
value	the value that is passed from the config file.
fdmcf	the 51Degrees main config.

Returns

the status code.

◆ ngx_http_51D_set_loc()

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

static

Forward declaration of ngx_http_51D_set_loc.

Set function.

Is called for occurrences of "51D_match_single", "51D_match_ua", "51D_match_ua_client_hints" or "51D_match_all" in a location config block. Allocates space for the header structure and initialises it with the set header function.

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_set_loc_cdn()

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

static

Forward declaration of ngx_http_51D_set_loc_cdn.

Set function.

Is called for occurrences of "51D_get_javascript_single" or "51D_javascript_all" in a location config block. Allocates space for the body structure and initialises it with the set body function.

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_set_loc_resp()

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

static

Forward declaration of ngx_http_51D_set_loc_resp.

Set function.

Is called for occurrences of "51D_set_resp_headers" 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_set_main()

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

static

Forward declaration of ngx_http_51D_set_main.

Set function.

Is called for occurrences of "51D_match_single", "51D_match_ua", "51D_match_ua_client_hints" or "51D_match_all" in a http config block. Allocates space for the header structure and initialises it with the set header function.

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_set_main_resp()

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

static

Forward declaration of ngx_http_51D_set_main_resp.

Set function.

Is called for occurrences of "51D_set_resp_headers" in a main 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_set_srv()

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

static

Forward declaration of ngx_http_51D_set_srv.

Set function.

Is called for occurrences of "51D_match_single", "51D_match_ua", "51D_match_ua_client_hints" or "51D_match_all" in a server config block. Allocates space for the header structure and initialises it with the set header function.

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_set_srv_resp()

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

static

Forward declaration of ngx_http_51D_set_srv_resp.

Set function.

Is called for occurrences of "51D_set_resp_headers" 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_shm_alloc()

void * ngx_http_51D_shm_alloc

(

size_t

__size

)

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_shm_alloc_aligned()

void * ngx_http_51D_shm_alloc_aligned	(	int	alignment,
		size_t	__size )

Shared memory alloc aligned function.

If the __size is not mulitple of alignment, it will be round up.

The method in Device Detection C is only used to allocate InterlockDoubleWidth whose size is 64bit on 32_bit system and 128 bit on 64_bit system.

The double width Interlock exchange requires allocated memory to be aligned to work. Nginx shared memory does not provide a mechanism to perform memory aligned allocation. However, without such API, normal ngx_slab_alloc should still be sufficient because of the way that shared memory is allocated and managed in Nginx.

The shared memory is allocated by mmap() which will always map on page-aligned address. The shared memory is then managed by ngx_slab_pool_t type which divides all shared zone into pages. Each page is used for allocating objects of the same size. Each ngx_slab_alloc require the specified size to be power of 2 and has minimum size of 8 bytes (64_bit). Nonconforming values are rounded up. Thus shared memory object will always be aligned on 64 bit boundary at least. Since the alignment of InterlockDoubleWidth object is at 32 bit on 32_bit system and 64 bit on 64 bit system, it will fit nicely on shared memory layout and is aligned properly.

P/s: How virtual memory address maintains alignment with physical memory address? It is because virtual memory address is combination of pages whose size is power of 2 (512 to 8192 with 4096 is typical), so when being mapped on physical memory the alignment will always be maintained. Additionally natural alignment of 32 bit system is 32 bit (*16=512) and 64 (*8=512) for 64 bit system, so when combined with strict minimum memory size of 8 bytes in Nginx shared memory slab model, the double width alignment will be preserved.

Parameters

alignment	of the requested memory block
__size	to be allocated

Returns

pointer to the allocated memory

◆ ngx_http_51D_shm_free()

void ngx_http_51D_shm_free

(

void *

__ptr

)

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_main_conf_t *	fdmcf,
		ngx_http_51D_data_to_set *	header,
		ngx_table_elt_t *	h[],
		int	matchIndex,
		int	haveMatch,
		ngx_str_t *	userAgent )

Process a request and perform device detection based on the request info.

This should perform a detection using either a User-Agent or all request header.

Parameters

r	the http request
fdmcf	the main configuration of 51Degrees module
header	the header name to set
h	the list of headers to store the match result
matchIndex	the index in the headers list to store the match values
haveMatch	indicate of a match has already been performed for input userAgent
userAgent	the user agent to perform the match for

Returns

code to indicate the status of the operation.

◆ removeUnknown()

void removeUnknown ( char * dest, ngx_int_t * charsAdded )

static

Remove Unknown string from a given string and updated the number of characers added with 'Unknown' being removed.

Parameters

dest	pointer to the string to be updated
charsAdded	number of characters added to the string that might contains Unknown. This will be updated after 'Unknown' string is removed.

◆ 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

◆ search_headers_in()

ngx_table_elt_t * search_headers_in ( ngx_http_request_t * r, u_char * name, size_t len )

static

Search headers function.

Searched request headers for the name supplied. Used when matching multiple http headers to find important headers. See: https://www.nginx.com/resources/wiki/start/topics/examples/headers_management

◆ set_data()

char * set_data ( ngx_conf_t * cf, ngx_http_51D_data_to_set * data, ngx_str_t * value, char * propertiesString, int propertiesCount, ngx_http_51D_main_conf_t * fdmcf )

static

Set data function.

Initialises the data structure for a given occurrence of "51D_match_single", "51D_match_ua", "51D_match_ua_client_hints", "51D_match_all", "51D_get_javascript_single" or "51D_get_javascript_all" 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.
propertiesString	command separated list of properties.
propertiesCount	number of properties in the string.
fdmcf	51Degrees main config.

Returns

Nginx status code.

◆ skipComponentName()

const char * skipComponentName ( const char * headerName )

static

Skip the component name in the header and return the pointer to the response header name.

Parameters

headerName

name of the SetHeader property, starting from the component part.

Returns

a pointer to the header name to set.

Variable Documentation

◆ ngx_http_51D_commands

ngx_command_t ngx_http_51D_commands[]

static

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

–51D_match_single takes two string arguments, the name of the header to be set and a comma separated list of properties to be returned. The thrid argument is optional to specify the query argument to be used over the default User-Agent. Is called within main, server and location block. Enables User-Agent matching. Deprecated in favor of 51D_match_ua. –51D_match_ua takes two string arguments, the name of the header to be set and a comma separated list of properties to be returned. The thrid argument is optional to specify the query argument to be used over the default User-Agent. Is called within main, server and location block. Enables User-Agent matching. –51D_match_all takes two string arguments, the name of the header to be set and a comma separated list of properties to be returned. Is called within main, server and location block. Enables multiple http header matching. –51D_get_javascript_single takes one string argument, the Javascript property to be returned. The second argument is optional to specify the query argument to be used over the User-Agent header. Is only called within the location block. This enables User-Agent matching to obtain the required Javascript property. –51D_get_javascript_all takes one string argument, the Javascript property to be returned. Is only called within the location block. This enables multiple http header matching. –51D_performance_profile takes one enum argument, the performance profile to set. Values can be "IN_MEMORY", "HIGH_PERFORMANCE", "LOW_MEMORY", "BALANCED", "BALANCED_TEMP", "DEFAULT". Currently only "IN_MEMORY" is supported. –51D_drift takes one integer argument, the drift value to set –51D_difference takes one integer argument, the difference value to set –51D_max_concurrency takes one integer argument, the maximum number of concurrency that the engine can be run with. In this case, it will be the number of worker processes. –51D_allow_unmatched takes one enum argument, which specifies whether unmatched result is allowed or not. This enum represents a boolean value. This is to be consistent with other integration such as Varnish. The values can be "on" or "off". –51D_use_performance_graph takes one enum argument, which specifies whether performance graph should be used. This enum represents a boolean value. DEPRECATED: has no effect and will be removed in future versions. –51D_use_predictive_graph takes one enum argument, which specifies whether predictive graph should be used. This enum represents a boolean value. DEPRECATED: has no effect and will be removed in the future versions. –51D_file_path takes one string argument, the path to a 51Degrees data file. Is called within server block. –51D_value_separator takes one string argument, the separator of the values being returned.

◆ ngx_http_51D_module

ngx_module_t ngx_http_51D_module

Initial value:

= {

NGX_MODULE_V1,

&ngx_http_51D_module_ctx,

ngx_http_51D_commands,

NGX_HTTP_MODULE,

NULL,

ngx_http_51D_init_module,

ngx_http_51D_init_process,

NULL,

NULL,

ngx_http_51D_exit_process,

ngx_http_51D_exit_master,

NGX_MODULE_V1_PADDING

}

Global module declaration.

Module definition.

Set the module context, commands, type and init function.

Examples

hash/config.conf, hash/gettingStarted.conf, hash/jsExample/javascript.conf, hash/matchMetrics.conf, hash/matchQuery.conf, hash/responseHeaders/responseHeader.conf, and mixed/gettingStarted.conf.

◆ ngx_http_51D_module_ctx

ngx_http_module_t ngx_http_51D_module_ctx

static

Initial value:

= {

NULL,

ngx_http_51D_post_conf,

ngx_http_51D_create_main_conf,

NULL,

ngx_http_51D_create_srv_conf,

ngx_http_51D_merge_srv_conf,

ngx_http_51D_create_loc_conf,

ngx_http_51D_merge_loc_conf,

}

Module context.

Sets the configuration functions.

◆ ngx_http_51D_performance_profiles

ngx_conf_enum_t ngx_http_51D_performance_profiles[]

static

Initial value:

= {

{ ngx_string("IN_MEMORY"), ngx_http_51D_profile_in_memory },

{ ngx_string("HIGH_PERFORMANCE"), ngx_http_51D_profile_high_performance },

{ ngx_string("LOW_MEMORY"), ngx_http_51D_profile_low_memory },

{ ngx_string("BALANCED"), ngx_http_51D_profile_balanced },

{ ngx_string("BALANCED_TEMP"), ngx_http_51D_profile_balanced_temp },

{ ngx_string("DEFAULT"), ngx_http_51D_profile_balanced },

{ ngx_null_string, 0 }

}

Performance profile map, to map user specified string with corresponding profile.

Have a data or code question? Get in touch and explore subscription options.