From da76459dc21b5af2449af2d36eb95226cb186ce2 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 28 Apr 2024 11:35:11 +0200 Subject: Adding upstream version 2.6.12. Signed-off-by: Daniel Baumann --- doc/DeviceAtlas-device-detection.txt | 82 ++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 doc/DeviceAtlas-device-detection.txt (limited to 'doc/DeviceAtlas-device-detection.txt') diff --git a/doc/DeviceAtlas-device-detection.txt b/doc/DeviceAtlas-device-detection.txt new file mode 100644 index 0000000..b600918 --- /dev/null +++ b/doc/DeviceAtlas-device-detection.txt @@ -0,0 +1,82 @@ +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. +The build supports the USE_PCRE and USE_PCRE2 options. Once extracted : + + $ make TARGET= USE_PCRE=1 (or USE_PCRE2=1) USE_DEVICEATLAS=1 DEVICEATLAS_SRC= + +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. However, if the API had been installed beforehand, DEVICEATLAS_SRC +can be omitted. Note that the DeviceAtlas C API version supported is the 2.4.0 +at minimum. + +For HAProxy developers who need to verify that their changes didn't accidentally +break the DeviceAtlas code, it is possible to build a dummy library provided in +the addons/deviceatlas/dummy directory and to use it as an alternative for the +full library. This will not provide the full functionalities, it will just allow +haproxy to start with a deviceatlas configuration, which generally is enough to +validate API changes : + + $ make TARGET= USE_PCRE=1 USE_DEVICEATLAS=1 DEVICEATLAS_SRC=$PWD/addons/deviceatlas/dummy + +These are supported DeviceAtlas directives (see doc/configuration.txt) : + - deviceatlas-json-file . + - deviceatlas-log-level (0 to 3, level of information returned by + the API, 0 by default). + - deviceatlas-property-separator (character used to separate the + properties produced by the API, | by default). + +Sample configuration : + + global + deviceatlas-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 converter + + 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" + +Optionally a JSON download scheduler is provided to allow a data file being +fetched automatically in a daily basis without restarting HAProxy : + + $ cd addons/deviceatlas && make [DEVICEATLAS_SRC=] + +Similarly, if the DeviceAtlas API is installed, DEVICEATLAS_SRC can be omitted. + + $ ./dadwsch -u JSON data file URL e.g. "https://deviceatlas.com/getJSON?licencekey=&format=zip&data=my&index=web" \ + [-p download directory path /tmp by default] \ + [-d scheduled hour of download, hour when the service is launched by default] + +Noted it needs to be started before HAProxy. + + +Please find more information about DeviceAtlas and the detection methods at +https://deviceatlas.com/resources . -- cgit v1.2.3