\r\n

51Degrees Device Detection Nginx  4.3

A device detection module for Nginx

51Degrees Nginx Module Internals

Detailed Description

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. More...
#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. More...
#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

Enumerations

enum  ngx_http_51D_performance_profile_e {
  ngx_http_51D_in_memory = 1, ngx_http_51D_high_performance, ngx_http_51D_low_memory, ngx_http_51D_balanced,
  ngx_http_51D_balanced_temp
}
Performance profiles enumerator. More...

Functions

static void *  ngx_http_51D_create_main_conf (ngx_conf_t *cf)
Forward declaration of ngx_http_51D_create_main_conf. More...
static void *  ngx_http_51D_create_srv_conf (ngx_conf_t *cf)
Forward declaration of ngx_http_51D_create_srv_conf. More...
static void *  ngx_http_51D_create_loc_conf (ngx_conf_t *cf)
Forward declaration of ngx_http_51D_create_loc_conf. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
static ngx_int_t  ngx_http_51D_handler (ngx_http_request_t *r)
Forward declaration of ngx_http_51D_handler. More...
static ngx_int_t  ngx_http_51D_header_filter (ngx_http_request_t *r)
Forward declaration of ngx_http_51D_header_filter. More...
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. More...
static ngx_int_t  ngx_http_51D_init_shm_resource_manager (ngx_shm_zone_t *shm_zone, void *data)
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. More...
static ngx_int_t  report_insufficient_memory_status (ngx_log_t *log)
Report the insufficient memory since memory allocation is a common activity. More...
static ConfigHash  get_config_hash (ngx_http_51D_main_conf_t *fdmcf)
Get a fiftyoneDegreesConfigHash instance based on the main configuration. More...
static ngx_int_t  ngx_http_51D_post_conf (ngx_conf_t *cf)
Module post config. More...
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. More...
void *  ngx_http_51D_shm_alloc (size_t __size)
Shared memory alloc function. More...
void *  ngx_http_51D_shm_alloc_aligned (int alignment, size_t __size)
Shared memory alloc aligned function. More...
void  ngx_http_51D_shm_free (void *__ptr)
Shared memory free function. More...
static ngx_int_t  ngx_http_51D_init_module (ngx_cycle_t *cycle)
Init module function. More...
static const char *  skipComponentName (const char *headerName)
Skip the component name in the header and return the pointer to the response header name. More...
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. More...
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. More...
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. More...
static ngx_int_t  ngx_http_51D_init_process (ngx_cycle_t *cycle)
Init process function. More...
void  ngx_http_51D_exit_process (ngx_cycle_t *cycle)
Exit process function. More...
void  ngx_http_51D_exit_master (ngx_cycle_t *cycle)
Exit master process. More...
static ngx_table_elt_t *  search_headers_in (ngx_http_request_t *r, u_char *name, size_t len)
Search headers function. More...
static void  add_value (char *delimiter, char *val, char *dst, size_t length)
Add value function. More...
static bool  is_metadata (char *val)
Check if a property being requested is a meta data property. More...
static ngx_str_t *  empty_string (ngx_http_request_t *r)
Create an empty ngx string from the http request pool. More...
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. More...
static void  add_override_evidence_from_cookie_and_query (ngx_http_request_t *r, ResultsHash *results, EvidenceKeyValuePairArray *evidence, ngx_array_t *cookies)
Add evidence required by the Hash device detection from cookie and query string. More...
static EvidenceKeyValuePairArray *  get_evidence (ResultsHash *results, ngx_http_request_t *r)
Create an evidence array and added the evidence from the http request. More...
ngx_uint_t  ngx_http_51D_get_match (ngx_http_51D_main_conf_t *fdmcf, ngx_http_request_t *r, int multi, ngx_str_t *userAgent)
Get match function. More...
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. More...
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. More...
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. More...
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. More...
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. More...
static ngx_table_elt_t *  findResponseHeader (ngx_http_request_t *r, ngx_str_t headerName)
Find a header in the response header list. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...

Variables

ngx_module_t  ngx_http_51D_module
Global module declaration. More...
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 ngx_conf_enum_t  ngx_http_51D_performance_profiles []
Performance profile map, to map user specified string with corresponding profile. More...
static ngx_command_t  ngx_http_51D_commands []
Definitions of functions which can be called from the config file. More...
static ngx_http_module_t  ngx_http_51D_module_ctx
Module context. More...

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.

Enumeration Type Documentation

Function Documentation

◆ add_override_evidence_from_cookie_and_query()

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.

Enumeration Type Documentation

Function Documentation

◆ add_override_evidence_from_cookie_and_query()

static void add_override_evidence_from_cookie_and_query ( ngx_http_request_t *   r,
ResultsHash *   results,
EvidenceKeyValuePairArray *   evidence,
ngx_array_t *   cookies  
)
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()

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

Parameters
delimiter - to split values with.
val - the string to add to dst.
dst - the string to append the val to.
length - the size remaining to append val to dst.

◆ empty_string()

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

static 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_evidence()

static EvidenceKeyValuePairArray* get_evidence ( ResultsHash *   results,
ngx_http_request_t *   r  
)
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
Returns
an array of evidence

◆ get_evidence_from_query_string()

static 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

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

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

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

◆ initRespHeaders()

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

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

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

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

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

static 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,
int   multi,
ngx_str_t *   userAgent  
)

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 - 0 for a single User-Agent match, 1 for a multiple HTTP header match.
userAgent - pointer to the user agent to perform the match on.
Returns
Nginx status code.

◆ ngx_http_51D_get_user_agent()

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

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

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

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

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

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

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

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

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

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

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

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

static 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" 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()

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

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

static 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" 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()

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

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

static 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" 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()

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

static 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" 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()

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

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

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

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

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  
)
static

Set data function.

Initialises the data structure for a given occurrence of "51D_match_single", "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()

static 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. –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. –51D_use_predictive_graph takes one enum argument, which specifies whether predictive graph should be used. This enum represents a boolean value. –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_MODULE,
NULL,
NULL,
NULL,
NGX_MODULE_V1_PADDING
}
static ngx_http_module_t ngx_http_51D_module_ctx
Module context.
Definition: ngx_http_51D_module.c:1102
static ngx_int_t ngx_http_51D_init_module(ngx_cycle_t *cycle)
Init module function.
Definition: ngx_http_51D_module.c:845
void ngx_http_51D_exit_master(ngx_cycle_t *cycle)
Exit master process.
Definition: ngx_http_51D_module.c:1395
static ngx_command_t ngx_http_51D_commands[]
Definitions of functions which can be called from the config file.
Definition: ngx_http_51D_module.c:961
void ngx_http_51D_exit_process(ngx_cycle_t *cycle)
Exit process function.
Definition: ngx_http_51D_module.c:1370
static ngx_int_t ngx_http_51D_init_process(ngx_cycle_t *cycle)
Init process function.
Definition: ngx_http_51D_module.c:1327

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, and hash/responseHeaders/responseHeader.conf.

◆ ngx_http_51D_module_ctx

ngx_http_module_t ngx_http_51D_module_ctx
static
Initial value:
= {
NULL,
NULL,
}
static ngx_int_t ngx_http_51D_post_conf(ngx_conf_t *cf)
Module post config.
Definition: ngx_http_51D_module.c:469
static void * ngx_http_51D_create_loc_conf(ngx_conf_t *cf)
Forward declaration of ngx_http_51D_create_loc_conf.
Definition: ngx_http_51D_module.c:628
static void * ngx_http_51D_create_main_conf(ngx_conf_t *cf)
Forward declaration of ngx_http_51D_create_main_conf.
Definition: ngx_http_51D_module.c:587
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.
Definition: ngx_http_51D_module.c:682
static void * ngx_http_51D_create_srv_conf(ngx_conf_t *cf)
Forward declaration of ngx_http_51D_create_srv_conf.
Definition: ngx_http_51D_module.c:646
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.
Definition: ngx_http_51D_module.c:663

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_in_memory },
{ ngx_string("HIGH_PERFORMANCE"), ngx_http_51D_high_performance },
{ ngx_string("LOW_MEMORY"), ngx_http_51D_low_memory },
{ ngx_string("BALANCED"), ngx_http_51D_balanced },
{ ngx_string("BALANCED_TEMP"), ngx_http_51D_balanced_temp },
{ ngx_string("DEFAULT"), ngx_http_51D_balanced },
{ ngx_null_string, 0 }
}

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