#- # Copyright (c) 2015-2016 Dridi Boukelmoune # Copyright 2017-2019 UPLEX - Nils Goroll Systemoptimierung # # Authors: Dridi Boukelmoune # Nils Goroll # # 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 dynamic 3 "Varnish dynamic backends module" .. role:: ref(emphasis) DESCRIPTION =========== This module provides a varnish director for dynamic creation of backends based on calls to * the system's network address resolution service which, in turn, typically use information from the ``/etc/hosts`` file and the Domain Name Service (DNS), but can be configured to use other sources like LDAP (see :ref:`nsswitch.conf(5)`). * or more advanced DNS resolution where `getdns`_ is available. While standard varnish backends defined in VCL may also be defined in terms of host names, changes of the name service information will only be picked up with a VCL reload. In contrast, for dynamic backends provided by this module, * name resolution information will be refreshed by background threads after a configurable time to live (ttl) or after the ttl from DNS with a `getdns`_ `vmod_dynamic.resolver`_. * resolution to multiple network addresses is supported In addition, with a `getdns`_ `vmod_dynamic.resolver`_, service discovery by DNS SRV records is possible, in which case this module also allows to configure host names (*targets*), their ports, priority and weight though DNS. See https://en.wikipedia.org/wiki/SRV_record for a good basic explanation and `vmod_dynamic.director.service`_ for details. .. _ref_vmod_dynamic_share: BACKEND SHARING =============== By default (``share = "DIRECTOR"`` parameter), backends are shared per director: Only one backend per director instance and ip address (and optionally port) is created. The ``share = "HOST"`` parameter allows to limit sharing to backends created for the same hostname (``host`` argument to the ``.backend()`` method). .. _ref_vmod_dynamic_probe: PROBING ======= A probe to be used with dynamically created backends can be specified. Note that with ``share = "DIRECTOR"``, a ``Host:`` header is only sent with probes if the ``host_header`` argument is provided during director initialization (or because a custom probe ``request`` contains one). With ``share = "HOST"``, the ``Host:`` header for probes defaults to the backend's hostname (``host`` argument to the ``.backend()`` method). Consider setting the ``initial`` attribute of probes at least as high as the ``threshold`` attribute. Otherwise transactions that trigger the first lookup of a domain will see a sick backend and fail. Irrespective of the ``initial`` attribute, transactions may still fail for backends which are actually sick. This can be mitigated using the ``retry`` transition in VCL. TTLs from DNS ============= With the default system resolver, TTLs from DNS are not supported optimally. While a good combination of a *ttl* parameter in combination with a system name service caching service like :ref:`nscd(8)` can achieve good results, to use TTLs from DNS, we recommend to compile this module with `getdns`_ support, configure a `vmod_dynamic.resolver`_ object and set the *ttl_from* parameter to either ``dns``, ``min`` or ``max`` as in this example:: sub vcl_init { new r = dynamic.resolver(); new d = dynamic.director( resolver = r.use(), ttl_from = dns ); } See `ref_ttl_from`_ for details. .. _ref_vmod_dynamic_names: NAMES ===== Directors and backends created by this vmod follow this naming scheme, which will be referred to as ** in the following documentation * ** The name of the VCL object created by `vmod_dynamic.director`_ * **\ (\ **\ :\ **\ ) A director (internally called *domain*), created as a result of a `vmod_dynamic.director.backend`_ or, indirectly, for targets resulting from a `vmod_dynamic.director.service`_ call. * **\ (\ *service*\ ) A director created as a result of a `vmod_dynamic.director.backend`_ or `vmod_dynamic.director.service`_ call. * **\ (\ *address*\ :\ *port*\ ) A dynamic backend for a **\ :\ ** with DIRECTOR scope sharing * **\ (\ *hostname*\ .\ *address*\ :\ *port*\ ) A dynamic backend for a **\ :\ ** with HOST scope sharing *port* may be represented symbolically (``http`` by default) STATISTICS ========== Dynamic backends are created and deleted on demand and can be monitored just like VCL-defined backends. Their statistics will appear in VSM-tools like ``varnishstat`` as:: VBE...* LOGGING ======= This module may log ``VCL_Log``, ``Error``, and ``Debug`` records following a common pattern:: vmod-dynamic: %s %s %s %s [ %s ] | | | | | | | | | +- Additional information | | | +------ Event | | +--------- without the part | +------------ Director name +--------------- VCL name Lookup timestamps are also logged to help troubleshooting, using regular ``Timestamp`` records with the following pattern for event labels:: vmod-dynamic . When a lookup thread is terminated, either because the VCL is cooling down or the ``domain_usage_timeout`` triggered, ``Timestamp`` records are logged with the event:: vmod-dynamic . Done Not all logs belong to HTTP transactions, especially since DNS lookups happen in the background. In order to capture all logs from this module the simplest way with varnishlog is the following:: varnishlog -g raw -q '* ~ vmod-dynamic' It displays any individual record that contains the string ``vmod-dynamic`` whether it belongs to a transaction or not. .. raw:: pdf PageBreak When a lookup fails, the backends are left untouched and the error will be logged with the following event:: getaddrinfo () $Event vmod_event $Object director( STRING port = "http", STRING host_header = 0, ENUM { DIRECTOR, HOST } share = "DIRECTOR", PROBE probe = 0, ACL whitelist = 0, DURATION ttl = 3600, DURATION connect_timeout = 0, DURATION first_byte_timeout = 0, DURATION between_bytes_timeout = 0, DURATION domain_usage_timeout = 7200, DURATION first_lookup_timeout = 10, INT max_connections = 0, INT proxy_header = 0, BLOB resolver = NULL, ENUM { cfg, dns, min, max } ttl_from = "cfg") Description Create a DNS director. The director creates backends with DNS lookups and chooses them in a round robin fashion. It accepts the following Parameters: - *port* (defaults to ``"http"``) The port to conncet to - *share* (defaults to ``"DIRECTOR"``) Backend sharing scope, see :ref:`ref_vmod_dynamic_share` - *host_header* (defaults to none) `host_header` attribute for dynamically created backends. See also :ref:`ref_vmod_dynamic_probe` - *probe* (defaults to none) Probe to use. See also :ref:`ref_vmod_dynamic_probe` - *whitelist* - an acl (defaults to none) Only name resolution results matching the acl will be used. - *ttl* - delay between lookups (defaults to one hour) Minimum configured backend lifetime before address resultion is re-checked, see also *ttl_from* - *domain_usage_timeout* Delay until an unused domain and its backends are removed (defaults to two hours) - *first_lookup_timeout* Delay until the director fails lookup when a domain is requested for the first time and there is no response from the name service (defaults to ten seconds) - *resolver* Use a particular resolver instance created with the `vmod_dynamic.resolver`_ constructor, if available. The argument to the *resolver* parameter must be the return value of the `vmod_dynamic.resolver.use`_ method. .. _ref_ttl_from: - *ttl_from* How to determine the minimum backend lifetime before address resultion is re-checked when a *resolver* is also used: - ``cfg``: Always use the *ttl* argument value (default) - ``dns``: Always use the ttl from the DNS response(s), falling back to the *ttl* argument value - ``min``: Use the minimum of the DNS response and the *ttl* argument value - ``max``: Use the maximum of the DNS response and the *ttl* argument value If there is more than one DNS response, the minimum if taken as the DNS ttl. For no *resolver*, only "cfg" is valid. For DNS failures, the *ttl* argument is used. Parameters to set attributes of backends See varnish documentation for details - *connect_timeout* (defaults to global *connect_timeout*) - *first_byte_timeout* (defaults to global *first_byte_timeout*) - *between_bytes_timeout* (defaults to global *between_bytes_timeout*) - *max_connections* (defaults to zero, unlimited) - *proxy_header* - version of the PROXY protocol to use, or zero to disable it (defaults to zero, valid versions are one or two) .. raw:: pdf PageBreak Example :: probe www_probe { .window = 8; .initial = 7; .threshold = 6; .interval = 5s; } acl www_acl { "192.168"/24; } sub vcl_init { new www_dir = dynamic.director( port = "80", probe = www_probe, whitelist = www_acl, ttl = 5m); } sub vcl_recv { set req.backend_hint = www_dir.backend("production.acme.com"); } .. raw:: pdf PageBreak $Method BACKEND .backend(STRING host = "", STRING port = "") Description Return a backend from the director for a given host name and port. If the host is not specified, it is picked from either ``bereq`` or ``req``. If the port is not speficied, it is taken from the director. $Method BACKEND .service(STRING service) Description Return a backend from the director for a service name (DNS SRV record). This Method is only supported when a `vmod_dynamic.resolver`_ object has been passed to the `vmod_dynamic.director`_ constructor. SRV records contain host (called target) and port information. Dynamic backends are automatically added and maintained based on this information as if `vmod_dynamic.director.backend`_ had been called. SRV records also contain *priority* and *weight* information. The `vmod_dynamic.director.service`_ method returns a target (backend) from the lowest *priority* found healthy. If there are multiple healthy targets for the lowest *priority*, one is chosen randomly based on the probabilities defined by the *weight* attributes. Note that it highly recommended to use a *probe* argument to the `vmod_dynamic.director`_ to avoid returning unresponsive backends. $Method VOID .debug(BOOL) Description Enable or disable debugging for a dynamic director, logging background operations related to backends management. $Object resolver( BOOL set_from_os=1, INT parallel=16) Create *parallel* `getdns`_ contexts to be used with the `vmod_dynamic.director`_ constructor - see `vmod_dynamic.resolver.use`_ Parameters: * *set_from_os*: whether defaults are taken from the operating system, see https://getdnsapi.net/documentation/spec/#8-dns-contexts for details * *parallel*: the number of contexts allocated. Each name resolution in progress requires one context. .. _ref_met_context: Additional configuration of the resolver contexts is possible through the methods documented below. Attempts to call these methods from outside ``vcl_init{}`` will trigger a VCL failure. .. _getdns: https://getdnsapi.net/ $Method BLOB .use() return a reference to the `vmod_dynamic.resolver`_ object for use as a parameter to the `vmod_dynamic.director`_ constructor. $Method BOOL .set_resolution_type(ENUM {RECURSING, STUB}) Specifies whether DNS queries are performed with nonrecurive lookups or as a stub resolver. May only be called from ``vcl_init{}`` See https://getdnsapi.net/documentation/spec/#83-contexts-for-basic-resolution $Method BOOL .clear_namespaces() Clear the list of namespaces to be configured, see below. May only be called from ``vcl_init{}`` $Method BOOL .add_namespace(ENUM {DNS, LOCALNAMES, NETBIOS, MDNS, NIS}) Add a namespace to the list of namespaces to be queried. This method only adds the namespace to an internal list, The actual configuration is only done once `vmod_dynamic.resolver.set_namespaces`_ is called. May only be called from ``vcl_init{}`` See https://getdnsapi.net/documentation/spec/#83-contexts-for-basic-resolution Notice that not all namespaces are available on all platforms. VCL load will fail with error ``312`` (The library did not have the requested API feature implemented.) in this case when `vmod_dynamic.resolver.set_namespaces`_ is called. $Method BOOL .set_namespaces() Apply namespace configuration, see above. May only be called from ``vcl_init{}`` $Method BOOL .clear_transports() Clear the list of transports to be configured, see below. May only be called from ``vcl_init{}`` $Method BOOL .add_transport(ENUM {UDP, TCP, TLS}) Add a transport to the list of transports to be tried. This method only adds the transport to an internal list, The actual configuration is only done once `vmod_dynamic.resolver.set_transports`_ is called. May only be called from ``vcl_init{}`` See https://getdnsapi.net/documentation/spec/#83-contexts-for-basic-resolution $Method BOOL .set_transports() Apply transport configuration, see above. May only be called from ``vcl_init{}`` $Method BOOL .set_idle_timeout(DURATION) Specifies the duration the API will leave an idle TCP or TLS connection open for (idle means no outstanding responses and no pending queries). May only be called from ``vcl_init{}`` $Method BOOL .set_limit_outstanding_queries(INT) May only be called from ``vcl_init{}`` $Method BOOL .set_timeout(DURATION) May only be called from ``vcl_init{}`` $Method BOOL .set_follow_redirects( ENUM {REDIRECTS_FOLLOW, REDIRECTS_DO_NOT_FOLLOW}) May only be called from ``vcl_init{}`` PITFALLS ======== There is no support for lookups limited to IPv4 or IPv6 only. However it can be achieved by the means of a white list:: acl ipv4_only { "0.0.0.0"/0; } acl ipv6_only { "::0"/0; } With that you can restrict backends to the desired IP network, and monitor error logs with the ``whitelist mismatch`` event. Knowing which addresses were rejected, you can fix your domains registration (DNS records, hosts file etc). SEE ALSO ======== * :ref:`vcl(7)` * :ref:`vsl(7)` * :ref:`vsl-query(7)` * :ref:`varnish-cli(7)` * :ref:`varnish-counters(7)` * :ref:`varnishstat(1)` * :ref:`getaddrinfo(3)` * :ref:`nscd(8)` * :ref:`nsswitch.conf(5)` Breaking CHANGES ================ 2.0 (2019-07-13) ---------------- * ``Error`` logging with ``acl-mismatch`` has been renamed to ``whitelist mismatch`` and port information has been added. * Port information has been added to director/backend names and the documentation section `ref_vmod_dynamic_names`_ has been added. ACKNOWLEDGEMENTS ================ We thank the various people and companies having made vmod_dynamic a reality: vmod_dynamic is based upon vmod_named developed and maintained from 2015 to 2017 by Dridi Boukelmoune (github @dridi) and supported by Varnish Software. Maintenance and improvements 2017 - 2019 were sponsored by various unnamed UPLEX clients and authored by Geoffrey Simmons and Nils Goroll from UPLEX. SRV record support and getdns integration in 2019 was supported by GOG.com vmod_dynamic also contains contributions by: Ricardo Nabinger Sanchez, Ryan Steinmetz