mirror of
http://git.haproxy.org/git/haproxy.git/
synced 2024-12-22 12:30:07 +00:00
DOC: move the device detection modules documentation to their own files
Both DeviceAtlas and 51Degrees used to put their building instructions in the README, representing more than 1/3 of it. It's better to let the README focus on generic stuff and building procedure and move the DD docs to their own files.
This commit is contained in:
Willy Tarreau
parent
d0027ed5b1
commit
29b25317fc
199
README
199
README
@ -220,199 +220,18 @@ disabled by setting USE_POLL="". For example :
|
||||
$ gmake TARGET=tiny USE_POLL="" TARGET_CFLAGS=-fomit-frame-pointer
|
||||
|
||||
|
||||
1.1) DeviceAtlas Device Detection
|
||||
---------------------------------
|
||||
1.1) Device Detection
|
||||
---------------------
|
||||
|
||||
In order to add DeviceAtlas Device Detection support, you would need to download
|
||||
the API source code from https://deviceatlas.com/deviceatlas-haproxy-module and
|
||||
once extracted :
|
||||
HAProxy supports several device detection modules relying on third party
|
||||
products. Some of them may provide free code, others free libs, others free
|
||||
evaluation licenses. Please read about their respective details in the
|
||||
following files :
|
||||
|
||||
$ make TARGET=<target> USE_PCRE=1 USE_DEVICEATLAS=1 DEVICEATLAS_SRC=<path to the API root folder>
|
||||
doc/DeviceAtlas-device-detection.txt for DeviceAtlas
|
||||
doc/51Degrees-device-detection.txt for 51Degrees
|
||||
doc/WURFL-device-detection.txt for Scientiamobile WURFL
|
||||
|
||||
Optionally DEVICEATLAS_INC and DEVICEATLAS_LIB may be set to override the path
|
||||
to the include files and libraries respectively if they're not in the source
|
||||
directory.
|
||||
|
||||
These are supported DeviceAtlas directives (see doc/configuration.txt) :
|
||||
- deviceatlas-json-file <path to the DeviceAtlas JSON data file>.
|
||||
- deviceatlas-log-level <number> (0 to 3, level of information returned by
|
||||
the API, 0 by default).
|
||||
- deviceatlas-property-separator <character> (character used to separate the
|
||||
properties produced by the API, | by default).
|
||||
|
||||
Sample configuration :
|
||||
|
||||
global
|
||||
deviceatlas-json-file <path to json file>
|
||||
|
||||
...
|
||||
frontend
|
||||
bind *:8881
|
||||
default_backend servers
|
||||
|
||||
There are two distinct methods available, one which leverages all HTTP headers
|
||||
and one which uses only a single HTTP header for the detection. The former
|
||||
method is highly recommended and more accurate. There are several possible use
|
||||
cases.
|
||||
|
||||
# To transmit the DeviceAtlas data downstream to the target application
|
||||
|
||||
All HTTP headers via the sample / fetch
|
||||
|
||||
http-request set-header X-DeviceAtlas-Data %[da-csv-fetch(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]
|
||||
|
||||
Single HTTP header (e.g. User-Agent) via the convertor
|
||||
|
||||
http-request set-header X-DeviceAtlas-Data %[req.fhdr(User-Agent),da-csv-conv(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]
|
||||
|
||||
# Mobile content switching with ACL
|
||||
|
||||
All HTTP headers
|
||||
|
||||
acl is_mobile da-csv-fetch(mobileDevice) 1
|
||||
|
||||
Single HTTP header
|
||||
|
||||
acl device_type_tablet req.fhdr(User-Agent),da-csv-conv(primaryHardwareType) "Tablet"
|
||||
|
||||
|
||||
Please find more information about DeviceAtlas and the detection methods at https://deviceatlas.com/resources .
|
||||
|
||||
|
||||
1.2) 51Degrees Device Detection
|
||||
-------------------------------
|
||||
|
||||
You can also include 51Degrees for inbuilt device detection enabling attributes
|
||||
such as screen size (physical & pixels), supported input methods, release date,
|
||||
hardware vendor and model, browser information, and device price among many
|
||||
others. Such information can be used to improve the user experience of a web
|
||||
site by tailoring the page content, layout and business processes to the
|
||||
precise characteristics of the device. Such customisations improve profit by
|
||||
making it easier for customers to get to the information or services they
|
||||
need. Attributes of the device making a web request can be added to HTTP
|
||||
headers as configurable parameters.
|
||||
|
||||
In order to enable 51Degrees download the 51Degrees source code from the
|
||||
official github repository :
|
||||
|
||||
git clone https://github.com/51Degrees/Device-Detection
|
||||
|
||||
then run 'make' with USE_51DEGREES and 51DEGREES_SRC set. Both 51DEGREES_INC
|
||||
and 51DEGREES_LIB may additionally be used to force specific different paths
|
||||
for .o and .h, but will default to 51DEGREES_SRC. Make sure to replace
|
||||
'51D_REPO_PATH' with the path to the 51Degrees repository.
|
||||
|
||||
51Degrees provide 2 different detection algorithms:
|
||||
|
||||
1. Pattern - balances main memory usage and CPU.
|
||||
2. Trie - a very high performance detection solution which uses more main
|
||||
memory than Pattern.
|
||||
|
||||
To make with 51Degrees Pattern algorithm use the following command line.
|
||||
|
||||
$ make TARGET=<target> USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/pattern
|
||||
|
||||
To use the 51Degrees Trie algorithm use the following command line.
|
||||
|
||||
$ make TARGET=<target> USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/trie
|
||||
|
||||
A data file containing information about devices, browsers, operating systems
|
||||
and their associated signatures is then needed. 51Degrees provide a free
|
||||
database with Github repo for this purpose. These free data files are located
|
||||
in '51D_REPO_PATH'/data with the extensions .dat for Pattern data and .trie for
|
||||
Trie data.
|
||||
|
||||
The configuration file needs to set the following parameters:
|
||||
|
||||
global
|
||||
51degrees-data-file path to the Pattern or Trie data file
|
||||
51degrees-property-name-list list of 51Degrees properties to detect
|
||||
51degrees-property-separator separator to use between values
|
||||
51degrees-cache-size LRU-based cache size (disabled by default)
|
||||
|
||||
The following is an example of the settings for Pattern.
|
||||
|
||||
global
|
||||
51degrees-data-file '51D_REPO_PATH'/data/51Degrees-LiteV3.2.dat
|
||||
51degrees-property-name-list IsTablet DeviceType IsMobile
|
||||
51degrees-property-separator ,
|
||||
51degrees-cache-size 10000
|
||||
|
||||
HAProxy needs a way to pass device information to the backend servers. This is
|
||||
done by using the 51d converter or fetch method, which intercepts the HTTP
|
||||
headers and creates some new headers. This is controlled in the frontend
|
||||
http-in section.
|
||||
|
||||
The following is an example which adds two new HTTP headers prefixed X-51D-
|
||||
|
||||
frontend http-in
|
||||
bind *:8081
|
||||
default_backend servers
|
||||
http-request set-header X-51D-DeviceTypeMobileTablet %[51d.all(DeviceType,IsMobile,IsTablet)]
|
||||
http-request set-header X-51D-Tablet %[51d.all(IsTablet)]
|
||||
|
||||
Here, two headers are created with 51Degrees data, X-51D-DeviceTypeMobileTablet
|
||||
and X-51D-Tablet. Any number of headers can be created this way and can be
|
||||
named anything. 51d.all( ) invokes the 51degrees fetch. It can be passed up to
|
||||
five property names of values to return. Values will be returned in the same
|
||||
order, seperated by the 51-degrees-property-separator configured earlier. If a
|
||||
property name can't be found the value 'NoData' is returned instead.
|
||||
|
||||
In addition to the device properties three additional properties related to the
|
||||
validity of the result can be returned when used with the Pattern method. The
|
||||
following example shows how Method, Difference and Rank could be included as one
|
||||
new HTTP header X-51D-Stats.
|
||||
|
||||
frontend http-in
|
||||
...
|
||||
http-request set-header X-51D-Stats %[51d.all(Method,Difference,Rank)]
|
||||
|
||||
These values indicate how confident 51Degrees is in the result that that was
|
||||
returned. More information is available on the 51Degrees web site at:
|
||||
|
||||
https://51degrees.com/support/documentation/pattern
|
||||
|
||||
The above 51d.all fetch method uses all available HTTP headers for detection. A
|
||||
modest performance improvement can be obtained by only passing one HTTP header
|
||||
to the detection method with the 51d.single converter. The following example
|
||||
uses the User-Agent HTTP header only for detection.
|
||||
|
||||
frontend http-in
|
||||
...
|
||||
http-request set-header X-51D-DeviceTypeMobileTablet %[req.fhdr(User-Agent),51d.single(DeviceType,IsMobile,IsTablet)]
|
||||
|
||||
Any HTTP header could be used inplace of User-Agent by changing the parameter
|
||||
provided to req.fhdr.
|
||||
|
||||
When compiled to use the Trie detection method the trie format data file needs
|
||||
to be provided. Changing the extension of the data file from dat to trie will
|
||||
use the correct data.
|
||||
|
||||
global
|
||||
51degrees-data-file '51D_REPO_PATH'/data/51Degrees-LiteV3.2.trie
|
||||
|
||||
When used with Trie the Method, Difference and Rank properties are not
|
||||
available.
|
||||
|
||||
The free Lite data file contains information about screen size in pixels and
|
||||
whether the device is a mobile. A full list of available properties is located
|
||||
on the 51Degrees web site at:
|
||||
|
||||
https://51degrees.com/resources/property-dictionary
|
||||
|
||||
Some properties are only available in the paid for Premium and Enterprise
|
||||
versions of 51Degrees. These data sets not only contain more properties but
|
||||
are updated weekly and daily and contain signatures for 100,000s of different
|
||||
device combinations. For more information see the data options comparison web
|
||||
page:
|
||||
|
||||
https://51degrees.com/compare-data-options
|
||||
|
||||
|
||||
1.3) Scientiamobile WURFL Device Detection
|
||||
-------------------------------
|
||||
|
||||
Please see doc/WURFL-device-detection.txt
|
||||
|
||||
2) How to install it
|
||||
--------------------
|
||||
|
||||
128
doc/51Degrees-device-detection.txt
Normal file
128
doc/51Degrees-device-detection.txt
Normal file
@ -0,0 +1,128 @@
|
||||
51Degrees Device Detection
|
||||
--------------------------
|
||||
|
||||
You can also include 51Degrees for inbuilt device detection enabling attributes
|
||||
such as screen size (physical & pixels), supported input methods, release date,
|
||||
hardware vendor and model, browser information, and device price among many
|
||||
others. Such information can be used to improve the user experience of a web
|
||||
site by tailoring the page content, layout and business processes to the
|
||||
precise characteristics of the device. Such customisations improve profit by
|
||||
making it easier for customers to get to the information or services they
|
||||
need. Attributes of the device making a web request can be added to HTTP
|
||||
headers as configurable parameters.
|
||||
|
||||
In order to enable 51Degrees download the 51Degrees source code from the
|
||||
official github repository :
|
||||
|
||||
git clone https://github.com/51Degrees/Device-Detection
|
||||
|
||||
then run 'make' with USE_51DEGREES and 51DEGREES_SRC set. Both 51DEGREES_INC
|
||||
and 51DEGREES_LIB may additionally be used to force specific different paths
|
||||
for .o and .h, but will default to 51DEGREES_SRC. Make sure to replace
|
||||
'51D_REPO_PATH' with the path to the 51Degrees repository.
|
||||
|
||||
51Degrees provide 2 different detection algorithms:
|
||||
|
||||
1. Pattern - balances main memory usage and CPU.
|
||||
2. Trie - a very high performance detection solution which uses more main
|
||||
memory than Pattern.
|
||||
|
||||
To make with 51Degrees Pattern algorithm use the following command line.
|
||||
|
||||
$ make TARGET=<target> USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/pattern
|
||||
|
||||
To use the 51Degrees Trie algorithm use the following command line.
|
||||
|
||||
$ make TARGET=<target> USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/trie
|
||||
|
||||
A data file containing information about devices, browsers, operating systems
|
||||
and their associated signatures is then needed. 51Degrees provide a free
|
||||
database with Github repo for this purpose. These free data files are located
|
||||
in '51D_REPO_PATH'/data with the extensions .dat for Pattern data and .trie for
|
||||
Trie data.
|
||||
|
||||
The configuration file needs to set the following parameters:
|
||||
|
||||
global
|
||||
51degrees-data-file path to the Pattern or Trie data file
|
||||
51degrees-property-name-list list of 51Degrees properties to detect
|
||||
51degrees-property-separator separator to use between values
|
||||
51degrees-cache-size LRU-based cache size (disabled by default)
|
||||
|
||||
The following is an example of the settings for Pattern.
|
||||
|
||||
global
|
||||
51degrees-data-file '51D_REPO_PATH'/data/51Degrees-LiteV3.2.dat
|
||||
51degrees-property-name-list IsTablet DeviceType IsMobile
|
||||
51degrees-property-separator ,
|
||||
51degrees-cache-size 10000
|
||||
|
||||
HAProxy needs a way to pass device information to the backend servers. This is
|
||||
done by using the 51d converter or fetch method, which intercepts the HTTP
|
||||
headers and creates some new headers. This is controlled in the frontend
|
||||
http-in section.
|
||||
|
||||
The following is an example which adds two new HTTP headers prefixed X-51D-
|
||||
|
||||
frontend http-in
|
||||
bind *:8081
|
||||
default_backend servers
|
||||
http-request set-header X-51D-DeviceTypeMobileTablet %[51d.all(DeviceType,IsMobile,IsTablet)]
|
||||
http-request set-header X-51D-Tablet %[51d.all(IsTablet)]
|
||||
|
||||
Here, two headers are created with 51Degrees data, X-51D-DeviceTypeMobileTablet
|
||||
and X-51D-Tablet. Any number of headers can be created this way and can be
|
||||
named anything. 51d.all( ) invokes the 51degrees fetch. It can be passed up to
|
||||
five property names of values to return. Values will be returned in the same
|
||||
order, seperated by the 51-degrees-property-separator configured earlier. If a
|
||||
property name can't be found the value 'NoData' is returned instead.
|
||||
|
||||
In addition to the device properties three additional properties related to the
|
||||
validity of the result can be returned when used with the Pattern method. The
|
||||
following example shows how Method, Difference and Rank could be included as one
|
||||
new HTTP header X-51D-Stats.
|
||||
|
||||
frontend http-in
|
||||
...
|
||||
http-request set-header X-51D-Stats %[51d.all(Method,Difference,Rank)]
|
||||
|
||||
These values indicate how confident 51Degrees is in the result that that was
|
||||
returned. More information is available on the 51Degrees web site at:
|
||||
|
||||
https://51degrees.com/support/documentation/pattern
|
||||
|
||||
The above 51d.all fetch method uses all available HTTP headers for detection. A
|
||||
modest performance improvement can be obtained by only passing one HTTP header
|
||||
to the detection method with the 51d.single converter. The following example
|
||||
uses the User-Agent HTTP header only for detection.
|
||||
|
||||
frontend http-in
|
||||
...
|
||||
http-request set-header X-51D-DeviceTypeMobileTablet %[req.fhdr(User-Agent),51d.single(DeviceType,IsMobile,IsTablet)]
|
||||
|
||||
Any HTTP header could be used inplace of User-Agent by changing the parameter
|
||||
provided to req.fhdr.
|
||||
|
||||
When compiled to use the Trie detection method the trie format data file needs
|
||||
to be provided. Changing the extension of the data file from dat to trie will
|
||||
use the correct data.
|
||||
|
||||
global
|
||||
51degrees-data-file '51D_REPO_PATH'/data/51Degrees-LiteV3.2.trie
|
||||
|
||||
When used with Trie the Method, Difference and Rank properties are not
|
||||
available.
|
||||
|
||||
The free Lite data file contains information about screen size in pixels and
|
||||
whether the device is a mobile. A full list of available properties is located
|
||||
on the 51Degrees web site at:
|
||||
|
||||
https://51degrees.com/resources/property-dictionary
|
||||
|
||||
Some properties are only available in the paid for Premium and Enterprise
|
||||
versions of 51Degrees. These data sets not only contain more properties but
|
||||
are updated weekly and daily and contain signatures for 100,000s of different
|
||||
device combinations. For more information see the data options comparison web
|
||||
page:
|
||||
|
||||
https://51degrees.com/compare-data-options
|
||||
57
doc/DeviceAtlas-device-detection.txt
Normal file
57
doc/DeviceAtlas-device-detection.txt
Normal file
@ -0,0 +1,57 @@
|
||||
DeviceAtlas Device Detection
|
||||
----------------------------
|
||||
|
||||
In order to add DeviceAtlas Device Detection support, you would need to download
|
||||
the API source code from https://deviceatlas.com/deviceatlas-haproxy-module and
|
||||
once extracted :
|
||||
|
||||
$ make TARGET=<target> USE_PCRE=1 USE_DEVICEATLAS=1 DEVICEATLAS_SRC=<path to the API root folder>
|
||||
|
||||
Optionally DEVICEATLAS_INC and DEVICEATLAS_LIB may be set to override the path
|
||||
to the include files and libraries respectively if they're not in the source
|
||||
directory.
|
||||
|
||||
These are supported DeviceAtlas directives (see doc/configuration.txt) :
|
||||
- deviceatlas-json-file <path to the DeviceAtlas JSON data file>.
|
||||
- deviceatlas-log-level <number> (0 to 3, level of information returned by
|
||||
the API, 0 by default).
|
||||
- deviceatlas-property-separator <character> (character used to separate the
|
||||
properties produced by the API, | by default).
|
||||
|
||||
Sample configuration :
|
||||
|
||||
global
|
||||
deviceatlas-json-file <path to json file>
|
||||
|
||||
...
|
||||
frontend
|
||||
bind *:8881
|
||||
default_backend servers
|
||||
|
||||
There are two distinct methods available, one which leverages all HTTP headers
|
||||
and one which uses only a single HTTP header for the detection. The former
|
||||
method is highly recommended and more accurate. There are several possible use
|
||||
cases.
|
||||
|
||||
# To transmit the DeviceAtlas data downstream to the target application
|
||||
|
||||
All HTTP headers via the sample / fetch
|
||||
|
||||
http-request set-header X-DeviceAtlas-Data %[da-csv-fetch(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]
|
||||
|
||||
Single HTTP header (e.g. User-Agent) via the convertor
|
||||
|
||||
http-request set-header X-DeviceAtlas-Data %[req.fhdr(User-Agent),da-csv-conv(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]
|
||||
|
||||
# Mobile content switching with ACL
|
||||
|
||||
All HTTP headers
|
||||
|
||||
acl is_mobile da-csv-fetch(mobileDevice) 1
|
||||
|
||||
Single HTTP header
|
||||
|
||||
acl device_type_tablet req.fhdr(User-Agent),da-csv-conv(primaryHardwareType) "Tablet"
|
||||
|
||||
|
||||
Please find more information about DeviceAtlas and the detection methods at https://deviceatlas.com/resources .
|
||||
@ -1,5 +1,5 @@
|
||||
Scientiamobile WURFL Device Detection
|
||||
-------------------------------
|
||||
-------------------------------------
|
||||
|
||||
You can also include WURFL for inbuilt device detection enabling attributes.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user