Commit 51c80ef6 authored by Nils Goroll's avatar Nils Goroll

6.2 compat

parent 8567d54e
# Copyright 2014-2016 UPLEX - Nils Goroll Systemoptimierung
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are
# met:
#
# 1. Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
#
# 2. Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the
# distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS *AS IS* AND
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
# WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
# OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
# IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
$Module dcs 3 "Varnish Device Classification Service Module"
::
import dcs [from "path"] ;
# typical use
sub vcl_recv {
set req.http.x-nb-classified = dcs.type_name(dcs.classify());
# - or-
set req.http.X-DeviceClass = dcs.type_class(dcs.classify());
# ...
}
DESCRIPTION
===========
This Varnish module provides an efficient implementation of device
detection and classification using the downloadable version of the
Netbiscuits Device Classifier Service (DCS) database. or a
self-provided database. An example database is included.
Netbiscuits Device Classifier Service (DCS) database
----------------------------------------------------
The DCS database is not part of this module and needs to be obtained
from Netbiscuits, please refer to
http://www.netbiscuits.com/device-detection/ as a starting point. With
sufficient privileges, a classifier token can be created on
https://my.netbiscuits.com/ under Account -> Token Management. See
http://kb.netbiscuits.com/dcs/dcs_ui_tokenmanagement.html for
instructions.
The classifier token is also referred to as DCS_KEY below.
Demo Database file
------------------
For demonstration purposes, we provice a simple database file with
some minimal and incomplete classification information in
`src/dcs_demo.db`. See :ref:using_the_demo_db for details.
Meta Classes
------------
Classification types from the database file can be associated with
meta-classes in the file `src/classes.conf`. Its format is
::
[classname]
Typename from the database
Note that the bundled tests need entries from the bundled
classes.conf.
During the build process, `gen_dcs_classifier.pl` emits warnings if
entries are missing from the classes configuration or if entries
remain unused. It may be advisable to update the configuration when
these warnigs are seen.
PERFORMANCE
-----------
This module was developed to provide exceptional performance compared
to previous implementations without requiring any changes to the
structure of the database or introducing any changes to the
semantics.
All lookups are uncached and lookup complexity does not depend on the
position of the best match in the dcs database.
To achieve high performance, C code for a custom parser for all tokens
(substrings) from the DCS database is generated. The parser is run to
detect all tokens from the User-Agent, marking potential matches. As
the match result, the DCS database entry which comes first in the
database is returned.
Exemplary benchmarks on a single i7-4600M core @2.9 GHz max suggest
that detection throughput exceeds 200.000 matches per second, which
corresponds to a latency in the order of 5us (5 microseconds).
.. _detection_methodology:
DETECTION METHODOLOGY
=====================
The following applies to the `classify()` function of the Varnish Module and Varnish 2
inline-C. The `dcs` command line tool only implements the last step.
* If the `x-wap-profile header` is present, the User-Agent will be
classified as a mobile phone
* If the `X-OperaMini-Phone-UA` header is present, the string " opera/
opera mini/ " gets appended to the `User-Agent` header for
classification.
* The contents of the headers `X-OperaMini-Phone-UA`,
`X-Device-User-Agent`, `X-Original-User-Agent` and `X-Goog-Source`
are appended to the `User-Agent` header for classification.
* The enrichted `User-Agent` string is passed to the DCS classifer and
the matching dcs db entry is returned - or a special db entry named
"unidentified".
$Event event
$Function INT classify()
Runs the :ref:detection_methodology as described.
The return value is the index of the DCS DB entry.
This vmod function should be used as an argument to one of the
functions described below.
As each invocation runs the classifcation again,
it should only be used once per request.
Example:
::
set req.http.x-nb-classified = dcs.type_name(dcs.classify());
$Function STRING entry_key(INT)
Returns the key of the dcs db entry whose index is given as the integer argument.
Example:
::
set req.http.xx-entry-key = dcs.entry_key(dcs.classify());
Might set `xx-entry-key` to something like "android*opera mini/"
$Function INT type_id(INT)
Returns the internal type id of the dcs db entry whose index is given as the integer argument.
Example:
::
set req.http.xx-type-id = dcs.type_id(dcs.classify());
Might set `xx-type-id` to "11"
$Function STRING type_name(INT)
Returns the type name of the dcs db entry whose index is given as the integer argument.
Example:
::
set req.http.x-nb-classified = dcs.type_name(dcs.classify());
might set `x-nb-classified` to "Mobile Phone"
$Function STRING type_class(INT)
Returns one of the meta types defined in `src/classes.conf`
Example:
::
set req.http.X-DeviceClass = dcs.type_class(dcs.classify());
might set `X-DeviceClass` to "smartphone"
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment