{"id":21054196,"url":"https://github.com/nigoroll/libvmod-dynamic","last_synced_at":"2025-07-03T02:05:35.044Z","repository":{"id":11109948,"uuid":"68390476","full_name":"nigoroll/libvmod-dynamic","owner":"nigoroll","description":"The Varnish dns/named director continued","archived":false,"fork":false,"pushed_at":"2025-06-30T11:04:43.000Z","size":724,"stargazers_count":101,"open_issues_count":5,"forks_count":37,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-06-30T12:22:57.333Z","etag":null,"topics":["director","dns","varnish","varnish-cache","vmod"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nigoroll.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"nigoroll"}},"created_at":"2016-09-16T15:13:13.000Z","updated_at":"2025-06-30T11:04:46.000Z","dependencies_parsed_at":"2023-02-14T10:31:09.384Z","dependency_job_id":"9f91a203-50c4-41de-a53a-d0b8fdbab120","html_url":"https://github.com/nigoroll/libvmod-dynamic","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/nigoroll/libvmod-dynamic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigoroll%2Flibvmod-dynamic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigoroll%2Flibvmod-dynamic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigoroll%2Flibvmod-dynamic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigoroll%2Flibvmod-dynamic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nigoroll","download_url":"https://codeload.github.com/nigoroll/libvmod-dynamic/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigoroll%2Flibvmod-dynamic/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263245294,"owners_count":23436511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["director","dns","varnish","varnish-cache","vmod"],"created_at":"2024-11-19T16:12:25.105Z","updated_at":"2025-07-03T02:05:35.023Z","avatar_url":"https://github.com/nigoroll.png","language":"C","funding_links":["https://github.com/sponsors/nigoroll","https://www.paypal.com/donate/?hosted_button_id=BTA6YE2H5VSXA"],"categories":[],"sub_categories":[],"readme":"============\nvmod_dynamic\n============\n\n.. role:: ref(emphasis)\n\nThis branch is for **Varnish-Cache after release 7.7**\n\nUse branch `7.7`_ with Varnish-Cache 7.7.x.\n\nSee `CHANGES.rst`_ to stay informed about important changes between\nversions.\n\n.. _7.7: https://github.com/nigoroll/libvmod-dynamic/tree/7.7\n\n.. _`CHANGES.rst`: CHANGES.rst\n\n-------------------------------\nVarnish dynamic backends module\n-------------------------------\n\nIntro / Typical Usage Example\n=============================\n\nThe typical use case for vmod_dynamic is to connect to TLS backends with\nmultiple DNS records.\n\n.. _`haproxy`: https://www.haproxy.org/\n\nTo achieve this, you need a *TLS onloader*, which turns clear text HTTP/1.1\nconnections into TLS connections. For this purpose, we recommend `haproxy`_. A\ntypical haproxy configuration snippet to provide an onloader service on a Unix\nDomain Socket (UDS) looks like this::\n\n    listen tls_onloader\n\tmode tcp\n\tmaxconn 1000\n\tbind /shared/varnish/tls_onloader.sock accept-proxy mode 777\n\tbalance roundrobin\n\tstick-table type ip size 100\n\tstick on dst\n\tserver s01 0.0.0.0:0 ssl ca-file /etc/ssl/certs/ca-bundle.crt alpn http/1.1 sni fc_pp_authority\n\tserver s02 0.0.0.0:0 ssl ca-file /etc/ssl/certs/ca-bundle.crt alpn http/1.1 sni fc_pp_authority\n\tserver s03 0.0.0.0:0 ssl ca-file /etc/ssl/certs/ca-bundle.crt alpn http/1.1 sni fc_pp_authority\n\tserver s04 0.0.0.0:0 ssl ca-file /etc/ssl/certs/ca-bundle.crt alpn http/1.1 sni fc_pp_authority\n\t# ...approximately as many servers as expected peers for improved tls session caching\n\nIn this snippet, ``/etc/ssl/certs/ca-bundle.crt`` should be replaced with a CA\ncertificate bundle which you decide to trust. ``maxconn`` should be adjusted as\nneeded. ``/shared/varnish/`` has to be a path which is also available to\n``varnishd`` (beware, for example, of systemd implicitly chrooting services).\n``mode 777`` is a fail-safe choice, but not optimal from a security perspective.\nIdeally, varnishd and haproxy should be added to the ``vcache`` group and have\nthis mode set to ``770``. The stick table ``size`` and the number of repetitions\nof the ``server sXX`` line should roughly match the number of expected peers.\n**NB:** all of this is just broad advise for the purpose of this introduction,\ndo your own research!\n\nOn the varnish end, the following VCL snippet configures a dynamic director\nusing the TLS onloader::\n\n    backend tls_onloader {\n        .path = \"/shared/varnish/tls_onloader.sock\";\n        ## consider setting:\n        # .connect_timeout = Xs;\n        # .first_byte_timeout = Xs;\n        # .between_bytes_timeout = Xs;\n    }\n\n    sub vcl_init {\n        new https = dynamic.director(via = tls_onloader, port = 443);\n    }\n\nNow https connections to backends can be initiated like this, for example::\n\n    sub vcl_backend_fetch {\n        set bereq.http.Host = \"example.com\";\n        set bereq.backend = https.backend();\n    }\n\nThat's it for the basics. Read on for more details and additional topics like\nTTL control, SRV record support, connection sharing options, timeouts, probes\nand more.\n\nDescription\n===========\n\n.. _`getdns`: https://getdnsapi.net/\n\nThis module provides a varnish director for dynamic creation of\nbackends based on calls to\n\n* the system's network address resolution service which, in turn,\n  typically use information from the ``/etc/hosts`` file and the\n  Domain Name Service (DNS), but can be configured to use other\n  sources like LDAP (see :ref:`nsswitch.conf(5)`).\n\n* or more advanced DNS resolution where `getdns`_ is available.\n\nWhile standard varnish backends defined in VCL may also be defined in\nterms of host names, changes of the name service information will only\nbe picked up with a VCL reload.\n\nIn contrast, for dynamic backends provided by this module,\n\n* name resolution information will be refreshed by background threads\n  after a configurable time to live (ttl) or after the ttl from DNS\n  with a `getdns`_ ``dynamic.resolver()``.\n\n* resolution to multiple network addresses is supported\n\nIn addition, with a `getdns`_ ``dynamic.resolver()``, service\ndiscovery by DNS SRV records is possible, in which case this module\nalso allows to configure host names (*targets*), their ports, priority\nand weight though DNS. See https://en.wikipedia.org/wiki/SRV_record\nfor a good basic explanation and ``xdirector.service()`` for\ndetails.\n\nINSTALLATION AND FURTHER READING\n================================\n\n.. _`INSTALL.rst`: INSTALL.rst\n\n.. _`vmod_dynamic.man.rst`: src/vmod_dynamic.man.rst\n\nSee `INSTALL.rst`_ for installation instructions.\n\nFor detailed usage documentation, see `vmod_dynamic.man.rst`_, which\nis also available as the :ref:`vmod_dynamic(3)` manual after\ninstallation.\n\nSUPPORT\n=======\n\n.. _github.com issues: https://github.com/nigoroll/libvmod-dynamic/issues\n\nTo report bugs, use `github.com issues`_.\n\nFor enquiries about professional service and support, please contact\ninfo@uplex.de\\ .\n\nCONTRIBUTING\n============\n\n.. _pull requests on github.com: https://github.com/nigoroll/libvmod-dynamic/pulls\n\nTo contribute to the project, please use `pull requests on github.com`_.\n\nTo support the project's development and maintenance, there are\nseveral options:\n\n.. _paypal: https://www.paypal.com/donate/?hosted_button_id=BTA6YE2H5VSXA\n\n.. _github sponsor: https://github.com/sponsors/nigoroll\n\n* Donate money through `paypal`_. If you wish to receive a commercial\n  invoice, please add your details (address, email, any requirements\n  on the invoice text) to the message sent with your donation.\n\n* Become a `github sponsor`_.\n\n* Contact info@uplex.de to receive a commercial invoice for SWIFT\n  payment.\n\nSEE ALSO\n========\n\n* :ref:`vcl(7)`\n* :ref:`vsl(7)`\n* :ref:`vsl-query(7)`\n* :ref:`varnish-cli(7)`\n* :ref:`varnish-counters(7)`\n* :ref:`varnishstat(1)`\n* :ref:`getaddrinfo(3)`\n* :ref:`nscd(8)`\n* :ref:`nsswitch.conf(5)`\n\nIf you want to learn more about DNS, you can start with `RFC 1034`_ and other\nRFCs that updated it over time. You may also have DNS already in place, or may\nbe interested in setting up a name server in your infrastructure. Below is a\nnon-exhaustive list of tools and services, but for free software name servers\nyou can have a look at debianadmin_.\n\n.. _RFC 1034: https://tools.ietf.org/html/rfc1034\n.. _debianadmin: http://www.debianadmin.com/open-source-domain-name-systemdns-servers.html\n\nDNS in the cloud (in alphabetic order):\n\n- AWS_\n- Azure_\n- `Digital Ocean`_\n- `Google Cloud`_\n- Heroku_\n\n.. _AWS: https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/using-instance-addressing.html\n.. _Azure: https://azure.microsoft.com/en-us/documentation/articles/dns-overview/\n.. _Digital Ocean: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-host-name-with-digitalocean\n.. _Google Cloud: https://cloud.google.com/dns/\n.. _Heroku: https://devcenter.heroku.com/articles/zerigo_dns\n\nDNS and containers (in alphabetic order):\n\n* `DC/OS`_ (Mesos)\n* `Docker Machine`_ (sort of)\n* Kubernetes_\n\n.. _DC/OS: https://docs.mesosphere.com/1.7/usage/service-discovery/mesos-dns/\n.. _Docker Machine: https://www.npmjs.com/package/docker-machine-dns\n.. _Kubernetes: http://kubernetes.io/docs/admin/dns/\n\nACKNOWLEDGEMENTS\n================\n\nWe thank the various people and companies having made vmod_dynamic a\nreality:\n\nvmod_dynamic is based upon vmod_named developed and maintained from\n2015 to 2017 by Dridi Boukelmoune (github @dridi) and supported by\nVarnish Software.\n\nMaintenance and improvements 2017 - 2019:\n\nGenerally sponsored by Spring Media and various unnamed UPLEX clients.\n\nSRV record support and getdns integration in 2019 was supported by\nGOG.com\n\nCode was written mostly by Geoffrey Simmons and Nils Goroll from UPLEX\nwith additional contributions by: Ricardo Nabinger Sanchez and\nRyan Steinmetz.\n\nThank you to all!\n\nCOPYRIGHT\n=========\n\n::\n\n  Copyright (c) 2015-2016 Dridi Boukelmoune\n  Copyright 2017-2023 UPLEX - Nils Goroll Systemoptimierung\n \n  Authors: Dridi Boukelmoune \u003cdridi.boukelmoune@gmail.com\u003e\n \t   Nils Goroll \u003cnils.goroll@uplex.de\u003e\n \n  Redistribution and use in source and binary forms, with or without\n  modification, are permitted provided that the following conditions\n  are met:\n  1. Redistributions of source code must retain the above copyright\n     notice, this list of conditions and the following disclaimer.\n  2. Redistributions in binary form must reproduce the above copyright\n     notice, this list of conditions and the following disclaimer in the\n     documentation and/or other materials provided with the distribution.\n \n  THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND\n  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\n  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE\n  ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE\n  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\n  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS\n  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT\n  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY\n  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF\n  SUCH DAMAGE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigoroll%2Flibvmod-dynamic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnigoroll%2Flibvmod-dynamic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigoroll%2Flibvmod-dynamic/lists"}