\r\n

51Degrees Device Detection Nginx  4.2Newer Version 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

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