[master] 6483ae21f Split backend and probe content out of vcl(7) to separate pages.
Poul-Henning Kamp
phk at FreeBSD.org
Tue Feb 16 11:08:07 UTC 2021
commit 6483ae21f96fd5f7f9cedae916524a7c619c17a8
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date: Tue Feb 16 11:07:12 2021 +0000
Split backend and probe content out of vcl(7) to separate pages.
diff --git a/doc/sphinx/reference/index.rst b/doc/sphinx/reference/index.rst
index 335c1d00f..2b8479243 100644
--- a/doc/sphinx/reference/index.rst
+++ b/doc/sphinx/reference/index.rst
@@ -10,7 +10,9 @@ The VCL language
.. toctree::
:maxdepth: 1
- VCL - Varnish Configuration Language <vcl>
+ VCL - The Varnish Configuration Language <vcl>
+ VCL backend configuration <vcl-backend>
+ VCL backend health probe <vcl-probe>
states.rst
VCL Design Patterns
diff --git a/doc/sphinx/reference/vcl-backend.rst b/doc/sphinx/reference/vcl-backend.rst
new file mode 100644
index 000000000..8d5472144
--- /dev/null
+++ b/doc/sphinx/reference/vcl-backend.rst
@@ -0,0 +1,157 @@
+.. role:: ref(emphasis)
+
+.. _vcl-backend(7):
+
+============
+VCL-backends
+============
+
+--------------------
+Configuring Backends
+--------------------
+
+:Manual section: 7
+
+.. _backend_definition:
+
+Backend definition
+------------------
+
+A backend declaration creates and initialises a named backend object.
+A declaration start with the keyword ``backend`` followed by the name of the
+backend. The actual declaration is in curly brackets, in a key/value fashion.::
+
+ backend name {
+ .attribute1 = value;
+ .attribute2 = value;
+ [...]
+ }
+
+If there is a backend named ``default`` it will be used unless another
+backend is explicitly set. If no backend is named ``default`` the first
+backend in the VCL program becomes the default.
+
+If you only use dynamic backends created by VMODs, an empty, always failing
+(503) backend can be specified::
+
+ backend default none;
+
+A backend must be specified with either a ``.host`` or a ``.path`` attribute, but
+not both. All other attributes have default values.
+
+Attribute ``.host``
+-------------------
+
+To specify a networked backend ``.host`` takes either a numeric
+IPv4/IPv6 address or a domain name which resolves to *at most*
+one IPv4 and one IPv6 address::
+
+ .host = "127.0.0.1";
+
+ .host = "[::1]:8080";
+
+ .host = "example.com:8081";
+
+The TCP port number can be specied as part of ``.host`` as a bove
+or separately using the ``.port`` attribute::
+
+ .port = 8081;
+
+Attribute ``.path``
+-------------------
+
+The absolute path to a Unix(4) domain socket of a local backend::
+
+ .path = "/var/run/http.sock";
+
+A warning will be issued if the uds-socket does not exist when the
+VCL is loaded. This makes it possible to start the UDS-listening peer,
+or set the socket file's permissions afterwards.
+
+If the uds-socket socket does not exist or permissions deny access,
+connection attempts will fail.
+
+Attribute ``.host_header``
+--------------------------
+
+A host header to add to probes and regular backend requests if they have no such header::
+
+ .host_header = "Host: example.com";
+
+Timeout Attributes
+------------------
+
+These attributes control how patient `varnishd` is during backend fetches::
+
+ .connect_timeout = 1.4s;
+ .first_byte_timeout = 20s;
+ .between_bytes_timeout = 10s;
+
+The default values comes parameters with the same names, see :ref:`varnishd(1)`.
+
+Attribute ``.max_connections``
+------------------------------
+
+Limit how many simultaneous connections varnish can open to the backend::
+
+ .max_connections = 1000;
+
+Attribute ``.proxy_header``
+---------------------------
+
+Send a PROXY protocol header to the backend with the ``client.ip`` and
+``server.ip`` values::
+
+ .proxy_header = 2;
+
+Legal values are one and two, depending which version of the PROXY protocol you want.
+
+*Notice* this setting will lead to backend connections being used
+for a single request only (subject to future improvements). Thus,
+extra care should be taken to avoid running into failing backend
+connections with EADDRNOTAVAIL due to no local ports being
+available. Possible options are:
+
+ * Use additional backend connections to extra IP addresses or TCP ports
+
+ * Increase the number of available ports (Linux sysctl ``net.ipv4.ip_local_port_range``)
+
+ * Reuse backend connection ports early (Linux sysctl ``net.ipv4.tcp_tw_reuse``)
+
+Attribute ``.preamble``
+-----------------------
+
+Send a BLOB on all newly opened connections to the backend::
+
+ .preamble = :SGVsbG8gV29ybGRcbgo=:;
+
+Attribute ``.probe``
+--------------------
+
+Please see :ref:`vcl-probe(7)`.
+
+SEE ALSO
+--------
+
+* :ref:`varnishd(1)`
+* :ref:`vcl(7)`
+* :ref:`vcl-probe(7)`
+* :ref:`vmod_directors(3)`
+* :ref:`vmod_std(3)`
+
+HISTORY
+-------
+
+VCL was developed by Poul-Henning Kamp in cooperation with Verdens
+Gang AS, Redpill Linpro and Varnish Software. This manual page is
+written by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland,
+Kristian Lyngstøl, Lasse Karstensen and others.
+
+COPYRIGHT
+---------
+
+This document is licensed under the same license as Varnish
+itself. See LICENSE for details.
+
+* Copyright (c) 2006 Verdens Gang AS
+* Copyright (c) 2006-2021 Varnish Software AS
diff --git a/doc/sphinx/reference/vcl-probe.rst b/doc/sphinx/reference/vcl-probe.rst
new file mode 100644
index 000000000..4268807c8
--- /dev/null
+++ b/doc/sphinx/reference/vcl-probe.rst
@@ -0,0 +1,183 @@
+.. role:: ref(emphasis)
+
+.. _vcl-probe(7):
+
+=========
+VCL-probe
+=========
+
+---------------------------------
+Configuring Backend Health Probes
+---------------------------------
+
+:Manual section: 7
+
+.. _reference-vcl_probes:
+
+Backend health probes
+---------------------
+
+Varnish can be configured to periodically send a request to test if a
+backend is answering and thus "healthy".
+
+Probes can be configured per backend::
+
+ backend foo {
+ [...]
+ .probe = {
+ [...]
+ }
+ }
+
+They can be named and shared between backends::
+
+ probe light {
+ [...]
+ }
+
+ backend foo {
+ .probe = light;
+ }
+
+ backend bar {
+ .probe = light;
+ }
+
+Or a ``default`` probe can be defined, which applies to all backends
+without a specific ``.probe`` configured::
+
+ probe default {
+ [...]
+ }
+
+The basic syntax is the same as for backends::
+
+ probe name {
+ .attribute1 = value;
+ .attribute2 = "value";
+ [...]
+ }
+
+There are no mandatory attributes, they all have defaults.
+
+Attribute ``.url``
+------------------
+
+The URL to query. Defaults to ``/``::
+
+ .url = "/health-probe";
+
+Attribute ``.request``
+----------------------
+
+Can be used to specify a full HTTP/1.1 request to be sent::
+
+ .request = "GET / HTTP/1.1"
+ "Host: example.com"
+ "X-Magic: We're fine with this."
+ "Connection: close";
+
+Each of the strings will have ``CRNL`` appended and a final HTTP
+header block terminating ``CRNL`` will be appended as well.
+
+Because connection shutdown is part of the health check,
+``Connection: close`` is mandatory.
+
+Attribute ``.expected_response``
+--------------------------------
+
+The expected HTTP status, defaults to ``200``::
+
+ .expected_response = 418;
+
+Attribute ``.timeout``
+----------------------
+
+How fast the probe must succeed, default is two seconds::
+
+ .timeout = 10s;
+
+Attribute ``.interval``
+-----------------------
+
+Time between probes, default is five seconds::
+
+ .interval = 1m;
+
+The backend health shift register
+---------------------------------
+
+Backend health probes uses a 64 stage shift register to remember the
+most recent health probes and to evaluate the total health of the backend.
+
+In the CLI, a good backend health status looks like this:
+
+.. code-block:: text
+
+ varnish> backend.list -p boot.backend
+ Backend name Admin Probe Health Last change
+ boot.backend probe 5/5 healthy Wed, 13 Jan 2021 10:31:50 GMT
+ Current states good: 5 threshold: 4 window: 5
+ Average response time of good probes: 0.000793
+ Oldest ================================================== Newest
+ 4444444444444444444444444444444444444444444444444444444444444444 Good IPv4
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Good Xmit
+ RRRRRRRRRRRRRRRRRRRRRRR----RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR Good Recv
+ HHHHHHHHHHHHHHHHHHHHHHH--------HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH Happy
+
+Starting from the bottom, the last line shows that this backend has been
+declared "Happy" for most the 64 health probes, but there were some
+trouble some while ago.
+
+However, in this case the ``.window`` is configured to five, and the
+``.threshold`` is set to four, so at this point in time, the backend
+is considered fully healthy.
+
+An additional ``.initial`` fills that many "happy" entries in the
+shift register when the VCL is loaded, so that backends can quickly
+become healthy, even if their health is normally considered over
+many samples::
+
+ .interval = 1s;
+ .window = 60;
+ .threshold = 45;
+ .initial = 43;
+
+This backend will be considered healthy if three out of four health
+probes in the last minute were good, but it becomes healthy as soon
+as two good probes have happened after the VCL was loaded.
+
+The default values are:
+
+* ``.window`` = 8
+
+* ``.threshold`` = 3
+
+* ``.initial`` = one less than ``.threshold``
+
+
+SEE ALSO
+========
+
+* :ref:`varnishd(1)`
+* :ref:`vcl(7)`
+* :ref:`vcl-backend(7)`
+* :ref:`vmod_directors(3)`
+* :ref:`vmod_std(3)`
+
+HISTORY
+=======
+
+VCL was developed by Poul-Henning Kamp in cooperation with Verdens
+Gang AS, Redpill Linpro and Varnish Software. This manual page is
+written by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland,
+Kristian Lyngstøl, Lasse Karstensen and others.
+
+COPYRIGHT
+=========
+
+This document is licensed under the same license as Varnish
+itself. See LICENSE for details.
+
+* Copyright (c) 2006 Verdens Gang AS
+* Copyright (c) 2006-2021 Varnish Software AS
diff --git a/doc/sphinx/reference/vcl.rst b/doc/sphinx/reference/vcl.rst
index d6f468e04..97fe80466 100644
--- a/doc/sphinx/reference/vcl.rst
+++ b/doc/sphinx/reference/vcl.rst
@@ -214,157 +214,10 @@ Example::
*/
}
-.. _backend_definition:
-
-Backend definition
-------------------
-
-A backend declaration creates and initialises a named backend object. A
-declaration start with the keyword ``backend`` followed by the name of the
-backend. The actual declaration is in curly brackets, in a key/value fashion.::
-
- backend name {
- .attribute = "value";
- }
-
-One of the attributes ``.host`` or ``.path`` is mandatory (but not
-both). The attributes will inherit their defaults from the global
-parameters. The following attributes are available:
-
- ``.host``
- The host to be used. IP address or a hostname that resolves to a
- single IP address. This attribute is mandatory, unless ``.path``
- is declared.
-
- ``.path`` (``VCL >= 4.1``)
-
- The absolute path of a Unix domain socket at which a backend is
- listening. If the file at that path does not exist or is not
- accessible to Varnish at VCL load time, then the VCL compiler
- issues a warning, but does not fail. This makes it possible to
- start the UDS-listening peer, or set the socket file's
- permissions, after starting Varnish or loading VCL with a UDS
- backend. But the socket file must exist and have necessary
- permissions before the first connection is attempted, otherwise
- fetches will fail. If the file does exist and is accessible, then
- it must be a socket; otherwise the VCL load fails. One of
- ``.path`` or ``.host`` must be declared (but not both). ``.path``
- may only be used in VCL since version 4.1.
-
- ``.port``
- The port on the backend that Varnish should connect to. Ignored if
- a Unix domain socket is declared in ``.path``.
-
- ``.host_header``
- A host header to add to probes and regular backend requests if they have no
- such header.
-
- ``.connect_timeout``
- Timeout for connections.
-
- Default: ``connect_timeout`` parameter, see :ref:`varnishd(1)`
-
- ``.first_byte_timeout``
- Timeout for first byte.
-
- Default: ``first_byte_timeout`` parameter, see :ref:`varnishd(1)`
-
- ``.between_bytes_timeout``
- Timeout between bytes.
-
- Default: ``between_bytes_timeout`` parameter, see :ref:`varnishd(1)`
-
- ``.probe``
- Attach a probe to the backend. See `Probes`_
-
- ``.proxy_header``
- The PROXY protocol version Varnish should use when connecting to
- this backend. Allowed values are ``1`` and ``2``.
-
- *Notice* this setting will lead to backend connections being used
- for a single request only (subject to future improvements). Thus,
- extra care should be taken to avoid running into failing backend
- connections with EADDRNOTAVAIL due to no local ports being
- available. Possible options are:
-
- * Use additional backend connections to extra IP addresses or TCP
- ports
-
- * Increase the number of available ports (Linux sysctl
- ``net.ipv4.ip_local_port_range``)
-
- * Reuse backend connection ports early (Linux sysctl
- ``net.ipv4.tcp_tw_reuse``)
-
- ``.max_connections``
- Maximum number of open connections towards this backend. If
- Varnish reaches the maximum Varnish it will start failing
- connections.
-
-Empty backends can also be defined using the following syntax.::
-
- backend name none;
-
-An empty backend will always return status code 503 as if it is sick.
-
-Backends can be used with *directors*. Please see the
-:ref:`vmod_directors(3)` man page for more information.
-
-.. _reference-vcl_probes:
-
-Probes
-------
-
-Probes will query the backend for status on a regular basis and mark
-the backend as down it they fail. A probe is defined as this::
-
- probe name {
- .attribute = "value";
- }
-
-The probe named ``default`` is special and will be used for all backends
-which do not explicitly reference a probe.
-
-There are no mandatory options. These are the options you can set:
-
- ``.url``
- The URL to query. Defaults to ``/``.
- Mutually exclusive with ``.request``
-
- ``.request``
- Specify a full HTTP request using multiple strings. ``.request`` will
- have ``\r\n`` automatically inserted after every string.
- Mutually exclusive with ``.url``.
-
- *Note* that probes require the backend to complete sending the
- response and close the connection within the specified timeout, so
- ``.request`` will, for ``HTTP/1.1``, most likely need to contain a
- ``"Connection: close"`` string.
-
- ``.expected_response``
- The expected HTTP response code. Defaults to ``200``.
-
- ``.timeout``
- The timeout for the probe. Default is ``2s``.
-
- ``.interval``
- How often the probe is run. Default is ``5s``.
-
- ``.initial``
- How many of the polls in ``.window`` are considered good when Varnish
- starts. Defaults to the value of ``.threshold`` - 1. In this case, the
- backend starts as sick and requires one single poll to be
- considered healthy.
-
- ``.window``
- How many of the latest polls we examine to determine backend health.
- Defaults to ``8``.
-
- ``.threshold``
- How many of the polls in ``.window`` must have succeeded to
- consider the backend to be healthy.
- Defaults to ``3``.
+Backends and health probes
+--------------------------
+Please see :ref:`vcl-backend(7)` and :ref:`vcl-probe(7)`
Access Control List (ACL)
-------------------------
@@ -542,6 +395,8 @@ SEE ALSO
========
* :ref:`varnishd(1)`
+* :ref:`vcl-backend(7)`
+* :ref:`vcl-probe(7)`
* :ref:`vmod_directors(3)`
* :ref:`vmod_std(3)`
diff --git a/man/Makefile.am b/man/Makefile.am
index 15bf7c9fc..bae551370 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -4,6 +4,8 @@ dist_man_MANS = \
varnish-cli.7 \
varnish-counters.7 \
vcl.7 \
+ vcl-backend.7 \
+ vcl-probe.7 \
vsl.7 \
vsl-query.7 \
varnishadm.1 \
@@ -48,6 +50,12 @@ vcl.7: $(top_builddir)/doc/sphinx/reference/vcl.rst \
$(top_srcdir)/bin/varnishd/builtin.vcl
$(BUILD_MAN) $(top_builddir)/doc/sphinx/reference/vcl.rst $@
+vcl-backend.7: $(top_builddir)/doc/sphinx/reference/vcl-backend.rst
+ $(BUILD_MAN) $(top_builddir)/doc/sphinx/reference/vcl-backend.rst $@
+
+vcl-probe.7: $(top_builddir)/doc/sphinx/reference/vcl-probe.rst
+ $(BUILD_MAN) $(top_builddir)/doc/sphinx/reference/vcl-probe.rst $@
+
vsl.7: $(top_builddir)/doc/sphinx/reference/vsl.rst \
$(top_builddir)/doc/sphinx/include/vsl-tags.rst
$(BUILD_MAN) $(top_builddir)/doc/sphinx/reference/vsl.rst $@
More information about the varnish-commit
mailing list