[master] 7b9e39f1c more vmod rst formatting cleanup
Nils Goroll
nils.goroll at uplex.de
Tue Feb 26 17:42:08 UTC 2019
commit 7b9e39f1c7d0a874edd7016e57d63daf8a70a036
Author: Nils Goroll <nils.goroll at uplex.de>
Date: Tue Feb 26 18:41:02 2019 +0100
more vmod rst formatting cleanup
Ref: doc/README.WRITING_RST.rst
diff --git a/lib/libvmod_blob/vmod.vcc b/lib/libvmod_blob/vmod.vcc
index 302293f76..5e34381a4 100644
--- a/lib/libvmod_blob/vmod.vcc
+++ b/lib/libvmod_blob/vmod.vcc
@@ -13,7 +13,7 @@ DESCRIPTION
===========
This VMOD provides utility functions and an object for the VCL data
-type BLOB, which may contain arbitrary data of any length.
+type ``BLOB``, which may contain arbitrary data of any length.
Examples::
@@ -71,24 +71,24 @@ ENUM values for an encoding scheme can be one of:
* ``HEX``
* ``URL``
-Empty strings are decoded into a "null blob" (of length 0),
-and conversely a null blob is encoded as the empty string.
+Empty strings are decoded into a "null blob" (of length 0), and
+conversely a null blob is encoded as the empty string.
-For encodings with ``HEX`` or ``URL``, you may also specify a ``case``
+For encodings with ``HEX`` or ``URL``, you may also specify a *case*
ENUM with one of the values ``LOWER``, ``UPPER`` or ``DEFAULT`` to
produce a string with lower- or uppercase hex digits (in ``[a-f]`` or
-``[A-F]``). The default value for ``case`` is ``DEFAULT``, which for
+``[A-F]``). The default value for *case* is ``DEFAULT``, which for
``HEX`` and ``URL`` means the same as ``LOWER``.
-The ``case`` ENUM is not relevant for decodings; ``HEX`` or ``URL``
+The *case* ENUM is not relevant for decodings; ``HEX`` or ``URL``
strings to be decoded as BLOBs may have hex digits in either case, or
in mixed case.
-The ``case`` ENUM MUST be set to ``DEFAULT`` for the other encodings
-(BASE64* and IDENTITY). You cannot, for example, produce an uppercase
-string by using the IDENTITY scheme with ``case=UPPER``. To change the
-case of a string, use the ``toupper`` or ``tolower`` functions from
-:ref:`vmod_std(3)`.
+The *case* ENUM MUST be set to ``DEFAULT`` for the other encodings
+(``BASE64*`` and ``IDENTITY``). You cannot, for example, produce an
+uppercase string by using the ``IDENTITY`` scheme with
+``case=UPPER``. To change the case of a string, use the ``std.toupper()`` or
+``std.tolower()`` functions from :ref:`vmod_std(3)`.
IDENTITY
~~~~~~~~
@@ -97,7 +97,7 @@ The simplest encoding converts between the BLOB and STRING data types,
leaving the contents byte-identical.
Note that a BLOB may contain a null byte at any position before its
-end; if such a BLOB is decoded with IDENTITY, the resulting STRING
+end; if such a BLOB is decoded with ``IDENTITY``, the resulting STRING
will have a null byte at that position. Since VCL strings, like C
strings, are represented with a terminating null byte, the string will
be truncated, appearing to contain less data than the original
@@ -109,15 +109,15 @@ blob. For example::
= blob.encode(IDENTITY, blob=blob.decode(HEX,
encoded="666f6f00626172"));
-IDENTITY is the default encoding and decoding. So the above can also
-be written as::
+``IDENTITY`` is the default encoding and decoding. So the above can
+also be written as::
# Decode from the hex encoding for "foo\0bar".
# The header will be seen as "foo".
set resp.http.Trunced-Foo2
= blob.encode(blob=blob.decode(HEX, encoded="666f6f00626172"));
-The ``case`` ENUM MUST be set to ``DEFAULT`` for ``IDENTITY`` encodings.
+The *case* ENUM MUST be set to ``DEFAULT`` for ``IDENTITY`` encodings.
BASE64*
~~~~~~~
@@ -139,14 +139,14 @@ The ``BASE64URLNOPAD`` encoding uses the same alphabet as
``BASE6URL``, but leaves out the padding. Thus the length of an
encoding with this scheme is not necessarily a multiple of four.
-The ``case`` ENUM MUST be set to ``DEFAULT`` for for all of the
+The *case* ENUM MUST be set to ``DEFAULT`` for for all of the
``BASE64*`` encodings.
HEX
~~~
The ``HEX`` encoding scheme converts hex strings into blobs and vice
-versa. For encodings, you may use the ``case`` ENUM to specify upper-
+versa. For encodings, you may use the *case* ENUM to specify upper-
or lowercase hex digits ``A`` through ``f`` (default ``DEFAULT``,
which means the same as ``LOWER``). A prefix such as ``0x`` is not
used for an encoding and is illegal for a decoding.
@@ -167,25 +167,25 @@ URL
~~~
The ``URL`` decoding replaces any ``%<2-hex-digits>`` substrings with
-the binary value of the hexadecimal number after the % sign.
+the binary value of the hexadecimal number after the ``%`` sign.
The ``URL`` encoding implements "percent encoding" as per RFC3986. The
-``case`` ENUM determines the case of the hex digits, but does not
+*case* ENUM determines the case of the hex digits, but does not
affect alphabetic characters that are not percent-encoded.
$Function BLOB decode(ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD,
HEX, URL} decoding="IDENTITY", INT length=0,
STRANDS encoded)
-Returns the BLOB derived from the string ``encoded`` according to the
-scheme specified by ``decoding``.
+Returns the BLOB derived from the string *encoded* according to the
+scheme specified by *decoding*.
-If ``length`` > 0, only decode the first ``length`` characters of the
-encoded string. If ``length`` <= 0 or greater than the length of the
-string, then decode the entire string. The default value of ``length``
+If *length* > 0, only decode the first *length* characters of the
+encoded string. If *length* <= 0 or greater than the length of the
+string, then decode the entire string. The default value of *length*
is 0.
-``decoding`` defaults to IDENTITY.
+*decoding* defaults to IDENTITY.
Example::
@@ -202,13 +202,14 @@ $Function STRING encode(ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD,
HEX, URL} encoding="IDENTITY",
ENUM {LOWER, UPPER, DEFAULT} case="DEFAULT", BLOB blob)
-Returns a string representation of the BLOB ``blob`` as specified by
-``encoding``. ``case`` determines the case of hex digits for the
-``HEX`` and ``URL`` encodings, and is ignored for the other encodings.
+Returns a string representation of the BLOB *blob* as specified by
+*encoding*. *case* determines the case of hex digits for the ``HEX``
+and ``URL`` encodings, and is ignored for the other encodings.
-``encoding`` defaults to IDENTITY, and ``case`` defaults to DEFAULT.
-DEFAULT is interpreted as LOWER for the HEX and URL encodings, and is
-the required value for the other encodings.
+*encoding* defaults to ``IDENTITY``, and *case* defaults to
+``DEFAULT``. ``DEFAULT`` is interpreted as ``LOWER`` for the ``HEX``
+and ``URL`` encodings, and is the required value for the other
+encodings.
Example::
@@ -234,18 +235,19 @@ $Function STRING transcode(ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD,
INT length=0, STRANDS encoded)
Translates from one encoding to another, by first decoding the string
-``encoded`` according to the scheme ``decoding``, and then returning
+*encoded* according to the scheme *decoding*, and then returning
the encoding of the resulting blob according to the scheme
-``encoding``. ``case`` determines the case of hex digits for the
+*encoding*. *case* determines the case of hex digits for the
``HEX`` and ``URL`` encodings, and is ignored for other encodings.
-As with ``decode()``: If ``length`` > 0, only decode the first
-``length`` characters of the encoded string, otherwise decode the
-entire string. The default value of ``length`` is 0.
+As with `vmod_blob.decode`_: If *length* > 0, only decode the first
+*length* characters of the encoded string, otherwise decode the
+entire string. The default value of *length* is 0.
-``decoding`` and ``encoding`` default to IDENTITY, and ``case``
-defaults to DEFAULT. DEFAULT is interpreted as LOWER for the HEX and
-URL encodings, and is the required value for the other encodings.
+*decoding* and *encoding* default to IDENTITY, and *case* defaults to
+``DEFAULT``. ``DEFAULT`` is interpreted as ``LOWER`` for the ``HEX``
+and ``URL`` encodings, and is the required value for the other
+encodings.
Example::
@@ -267,22 +269,23 @@ Example::
$Function BOOL same(BLOB, BLOB)
-Returns true if and only if the two BLOB arguments are the same
+Returns ``true`` if and only if the two BLOB arguments are the same
object, i.e. they specify exactly the same region of memory, or both
are empty.
If the BLOBs are both empty (length is 0 and/or the internal pointer
-is NULL), then ``same()`` returns ``true``. If any non-empty BLOB
-is compared to an empty BLOB, then ``same()`` returns ``false``.
+is ``NULL``), then `vmod_blob.same`_ returns ``true``. If any
+non-empty BLOB is compared to an empty BLOB, then `vmod_blob.same`_
+returns ``false``.
$Function BOOL equal(BLOB, BLOB)
Returns true if and only if the two BLOB arguments have equal contents
(possibly in different memory regions).
-As with ``same()``: If the BLOBs are both empty, then ``equal()``
+As with `vmod_blob.same`_: If the BLOBs are both empty, then `vmod_blob.equal`_
returns ``true``. If any non-empty BLOB is compared to an empty BLOB,
-then ``equal()`` returns ``false``.
+then `vmod_blob.equal`_ returns ``false``.
$Function INT length(BLOB)
@@ -290,11 +293,11 @@ Returns the length of the BLOB.
$Function BLOB sub(BLOB, BYTES length, BYTES offset = 0)
-Returns a new BLOB formed from ``length`` bytes of the BLOB argument
-starting at ``offset`` bytes from the start of its memory region. The
-default value of ``offset`` is 0B.
+Returns a new BLOB formed from *length* bytes of the BLOB argument
+starting at *offset* bytes from the start of its memory region. The
+default value of *offset* is ``0B``.
-``sub()`` fails and returns NULL if the BLOB argument is empty, or if
+`vmod_blob.sub`_ fails and returns NULL if the BLOB argument is empty, or if
``offset + length`` requires more bytes than are available in the
BLOB.
@@ -303,7 +306,7 @@ $Object blob(ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, HEX,
STRANDS encoded)
Creates an object that contains the BLOB derived from the string
-``encoded`` according to the scheme ``decoding``.
+*encoded* according to the scheme *decoding*.
Example::
@@ -335,7 +338,7 @@ $Method STRING .encode(ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, HEX,
ENUM {LOWER, UPPER, DEFAULT} case="DEFAULT")
Returns an encoding of BLOB created by the constructor, according to
-the scheme ``encoding``. ``case`` determines the case of hex digits
+the scheme *encoding*. *case* determines the case of hex digits
for the ``HEX`` and ``URL`` encodings, and MUST be set to ``DEFAULT``
for the other encodings.
@@ -347,71 +350,74 @@ Example::
# blob as base64
set resp.http.The-Blob-b64 = theblob1.encode(BASE64);
-For any ``blob`` object, encoding ``ENC`` and case ``CASE``, encodings
-via the ``.encode()`` method and the ``encode()`` function are equal::
+For any `vmod_blob.blob`_ object, `encoding` and `case`, encodings via
+the `vmod_blob.blob.encode`_ method and the `vmod_blob.encode`_
+function are equal::
# Always true:
blob.encode(ENC, CASE, blob.get()) == blob.encode(ENC, CASE)
-But the object method is more efficient -- the encoding is computed
-once and cached (with allocation in heap memory), and the cached
-encoding is retrieved on every subsequent call. The ``encode()``
-function computes the encoding on every call, allocating space for the
-string in Varnish workspaces.
+But the `vmod_blob.blob.encode`_ object method is more efficient --
+the encoding is computed once and cached (with allocation in heap
+memory), and the cached encoding is retrieved on every subsequent
+call. The `vmod_blob.encode`_ function computes the encoding on every
+call, allocating space for the string in Varnish workspaces.
So if the data in a BLOB are fixed at VCL initialization time, so that
its encodings will always be the same, it is better to create a
-``blob`` object. The VMOD's functions should be used for data that are
+`vmod_blob.blob`_ object. The VMOD's functions should be used for data that are
not known until runtime.
ERRORS
======
-The encoders, decoders and ``sub()`` may fail if there is insufficient
-space to create the new blob or string. Decoders may also fail if the
-encoded string is an illegal format for the decoding scheme. Encoders
-will fail for the ``IDENTITY`` and ``BASE64*`` encoding schemes if the
-``case`` ENUM is not set to ``DEFAULT``.
+The encoders, decoders and `vmod_blob.sub`_ may fail if there is
+insufficient space to create the new blob or string. Decoders may also
+fail if the encoded string is an illegal format for the decoding
+scheme. Encoders will fail for the ``IDENTITY`` and ``BASE64*``
+encoding schemes if the *case* ENUM is not set to ``DEFAULT``.
If any of the VMOD's methods, functions or constructor fail, then VCL
failure is invoked, just as if ``return(fail)`` had been called in the
VCL source. This means that:
-* If the ``blob`` object constructor fails, or if any methods or
- functions fail during ``vcl_init``, then the VCL program will fail
+* If the ``vmod_blob.blob`_ object constructor fails, or if any methods or
+ functions fail during ``vcl_init{}``, then the VCL program will fail
to load, and the VCC compiler will emit an error message.
* If a method or function fails in any other VCL subroutine besides
- ``vcl_synth``, then control is directed to ``vcl_synth``. The
+ ``vcl_synth{}``, then control is directed to ``vcl_synth{}``. The
response status is set to 503 with the reason string ``"VCL
- failed"``, and an error message will be written to the Varnish log
+ failed"``, and an error message will be written to the :ref:`vsl(7)`
using the tag ``VCL_Error``.
-* If the failure occurs during ``vcl_synth``, then ``vcl_synth`` is
- aborted. The response line ``"503 VCL failed"`` is returned, and
+* If the failure occurs during ``vcl_synth{}``, then ``vcl_synth{}``
+ is aborted. The response line ``"503 VCL failed"`` is returned, and
the ``VCL_Error`` message is written to the log.
LIMITATIONS
===========
The VMOD allocates memory in various ways for new blobs and
-strings. The ``blob`` object and its methods allocate memory from the
-heap, and hence they are only limited by available virtual memory.
+strings. The `vmod_blob.blob`_ object and its methods allocate memory
+from the heap, and hence they are only limited by available virtual
+memory.
-The ``encode()``, ``decode()`` and ``transcode()`` functions allocate
-Varnish workspace, as does ``sub()`` for the newly created BLOB. If
-these functions are failing, as indicated by "out of space" messages
-in the Varnish log (with the ``VCL_Error`` tag), then you will need to
-increase the varnishd parameters ``workspace_client`` and/or
-``workspace_backend``.
+The `vmod_blob.encode`_, `vmod_blob.decode`_ and
+`vmod_blob.transcode`_ functions allocate Varnish workspace, as does
+`vmod_blob.sub`_ for the newly created BLOB. If these functions are
+failing, as indicated by "out of space" messages in the Varnish log
+(with the ``VCL_Error`` tag), then you will need to increase the
+varnishd parameters ``workspace_client`` and/or ``workspace_backend``.
-The ``transcode()`` function also allocates space on the stack for a
-temporary BLOB. If this function causes stack overflow, you may need
-to increase the varnishd parameter ``thread_pool_stack``.
+The `vmod_blob.transcode`_ function also allocates space on the stack
+for a temporary BLOB. If this function causes stack overflow, you may
+need to increase the varnishd parameter ``thread_pool_stack``.
SEE ALSO
========
* :ref:`varnishd(1)`
* :ref:`vcl(7)`
+* :ref:`vsl(7)`
* :ref:`vmod_std(3)`
diff --git a/lib/libvmod_debug/vmod.vcc b/lib/libvmod_debug/vmod.vcc
index 016bca407..2ff1d0220 100644
--- a/lib/libvmod_debug/vmod.vcc
+++ b/lib/libvmod_debug/vmod.vcc
@@ -92,22 +92,22 @@ $Method VOID .test_priv_call(PRIV_CALL)
Test method for call private pointers
-Objects share the PRIV_* state with other objects and methods from the
-same vmod - IOW the PRIV_* state is per vmod, not per object.
+Objects share the ``PRIV_*`` state with other objects and methods from
+the same vmod - IOW the ``PRIV_*`` state is per vmod, not per object.
$Method VOID .test_priv_vcl(PRIV_VCL)
Test method for VCL private pointers
-Objects share the PRIV_* state with other objects and methods from the
-same vmod - IOW the PRIV_* state is per vmod, not per object.
+Objects share the ``PRIV_*`` state with other objects and methods from
+the same vmod - IOW the ``PRIV_*`` state is per vmod, not per object.
$Method STRING .test_priv_task(PRIV_TASK, STRING s="")
Test method for TASK private pointers
-Objects share the PRIV_* state with other objects and methods from the
-same vmod - IOW the PRIV_* state is per vmod, not per object.
+Objects share the ``PRIV_*`` state with other objects and methods from
+the same vmod - IOW the ``PRIV_*`` state is per vmod, not per object.
$Method STRING .test_priv_top(PRIV_TOP, STRING)
@@ -196,12 +196,12 @@ Return the string formed from the concatenation in the constructor.
$Function STRING concatenate(STRANDS)
Return the string formed by concatenating the given strings.
-(Uses VRT_StrandsWS().)
+(Uses ``VRT_StrandsWS()``.)
$Function STRING collect(STRANDS)
Return the string formed by concatenating the given strings.
-(Uses VRT_CollectStrands().)
+(Uses ``VRT_CollectStrands()``.)
$Function VOID sethdr(HEADER, STRANDS)
@@ -209,14 +209,15 @@ Set the given header with the concatenation of the given strings.
$Function DURATION priv_perf(INT size, INT rounds=10000)
-Benchmark VRT_priv_task() with `size` elements, iterating `rounds`
+Benchmark ``VRT_priv_task()`` with `size` elements, iterating `rounds`
times.
-Returns the average time taken for each call scaled up from nanoseconds
-to seconds - iow the value given as seconds is actually the duration
-in nanoseconds.
+Returns the average time taken for each call scaled up from
+nanoseconds to seconds - iow the value given as seconds is actually
+the duration in nanoseconds.
-For comparable results, a higher size run should called first and discarded.
+For comparable results, a higher size run should called first and
+discarded.
$Object NULL_OK obj_opt(PRIV_CALL, PRIV_VCL, PRIV_TASK,
[STRING s], [BOOL b])
diff --git a/lib/libvmod_directors/vmod.vcc b/lib/libvmod_directors/vmod.vcc
index f30f2b2a1..7a81ee422 100644
--- a/lib/libvmod_directors/vmod.vcc
+++ b/lib/libvmod_directors/vmod.vcc
@@ -38,7 +38,7 @@ $Module directors 3 "Varnish Directors Module"
DESCRIPTION
===========
-`vmod_directors` enables backend load balancing in Varnish.
+*vmod_directors* enables backend load balancing in Varnish.
The module implements load balancing techniques, and also serves as an
example on how one could extend the load balancing capabilities of
@@ -49,7 +49,7 @@ To enable load balancing you must import this vmod (directors).
Then you define your backends. Once you have the backends declared you
can add them to a director. This happens in executed VCL code. If you
want to emulate the previous behavior of Varnish 3.0 you can just
-initialize the directors in vcl_init, like this::
+initialize the directors in ``vcl_init{}``, like this::
sub vcl_init {
new vdir = directors.round_robin();
@@ -58,173 +58,183 @@ initialize the directors in vcl_init, like this::
}
As you can see there is nothing keeping you from manipulating the
-directors elsewhere in VCL. So, you could have VCL code that would
-add more backends to a director when a certain URL is called.
+directors elsewhere in VCL. So, you could have VCL code that would add
+more backends to a director when a certain URL is called.
Note that directors can use other directors as backends.
$Object round_robin()
-Description
- Create a round robin director.
+Create a round robin director.
+
+This director will pick backends in a round robin fashion.
+
+Example::
- This director will pick backends in a round robin fashion.
-Example
new vdir = directors.round_robin();
$Method VOID .add_backend(BACKEND)
-Description
- Add a backend to the round-robin director.
-Example
+Add a backend to the round-robin director.
+
+Example::
+
vdir.add_backend(backend1);
$Method VOID .remove_backend(BACKEND)
-Description
- Remove a backend from the round-robin director.
-Example
+Remove a backend from the round-robin director.
+
+Example::
+
vdir.remove_backend(backend1);
$Method BACKEND .backend()
-Description
- Pick a backend from the director.
-Example
+Pick a backend from the director.
+
+Example::
+
set req.backend_hint = vdir.backend();
$Object fallback(BOOL sticky = 0)
-Description
- Create a fallback director.
+Create a fallback director.
- A fallback director will try each of the added backends in turn,
- and return the first one that is healthy.
+A fallback director will try each of the added backends in turn, and
+return the first one that is healthy.
- If ``sticky`` is set to true, the director will keep using the healthy
- backend, even if a higher-priority backend becomes available. Once the
- whole backend list is exhausted, it'll start over at the beginning.
+If *sticky* is set to ``true``, the director will keep using the
+healthy backend, even if a higher-priority backend becomes
+available. Once the whole backend list is exhausted, it'll start over
+at the beginning.
+
+Example::
-Example
new vdir = directors.fallback();
$Method VOID .add_backend(BACKEND)
-Description
- Add a backend to the director.
+Add a backend to the director.
+
+Note that the order in which this is done matters for the fallback
+director.
- Note that the order in which this is done matters for the fallback
- director.
+Example::
-Example
vdir.add_backend(backend1);
$Method VOID .remove_backend(BACKEND)
-Description
- Remove a backend from the director.
-Example
+Remove a backend from the director.
+
+Example::
+
vdir.remove_backend(backend1);
$Method BACKEND .backend()
-Description
- Pick a backend from the director.
-Example
- set req.backend_hint = vdir.backend();
+Pick a backend from the director.
+
+Example::
+ set req.backend_hint = vdir.backend();
$Object random()
-Description
- Create a random backend director.
+Create a random backend director.
- The random director distributes load over the backends using
- a weighted random probability distribution.
- The "testable" random generator in varnishd is used, which
- enables deterministic tests to be run (See: d00004.vtc).
+The random director distributes load over the backends using a
+weighted random probability distribution.
+
+The "testable" random generator in varnishd is used, which enables
+deterministic tests to be run (See: ``d00004.vtc``).
+
+Example::
-Example
new vdir = directors.random();
$Method VOID .add_backend(BACKEND, REAL)
-Description
- Add a backend to the director with a given weight.
+Add a backend to the director with a given weight.
- Each backend will receive approximately 100 * (weight /
- (sum(all_added_weights))) per cent of the traffic sent to this
- director.
+Each backend will receive approximately 100 * (weight /
+(sum(all_added_weights))) per cent of the traffic sent to this
+director.
-Example
- | # 2/3 to backend1, 1/3 to backend2.
- | vdir.add_backend(backend1, 10.0);
- | vdir.add_backend(backend2, 5.0);
+Example::
+
+ # 2/3 to backend1, 1/3 to backend2.
+ vdir.add_backend(backend1, 10.0);
+ vdir.add_backend(backend2, 5.0);
$Method VOID .remove_backend(BACKEND)
-Description
- Remove a backend from the director.
-Example
+Remove a backend from the director.
+
+Example::
+
vdir.remove_backend(backend1);
$Method BACKEND .backend()
-Description
- Pick a backend from the director.
-Example
+Pick a backend from the director.
+
+Example::
+
set req.backend_hint = vdir.backend();
$Object hash()
-Description
- Create a hashing backend director.
+Create a hashing backend director.
+
+The director chooses the backend server by computing a hash/digest of
+the string given to `vmod_directors.hash.backend`_.
- The director chooses the backend server by computing a hash/digest
- of the string given to .backend().
+Commonly used with ``client.ip`` or a session cookie to get sticky
+sessions.
- Commonly used with ``client.ip`` or a session cookie to get
- sticky sessions.
+Example::
-Example
new vdir = directors.hash();
$Method VOID .add_backend(BACKEND, REAL)
-Description
- Add a backend to the director with a certain weight.
+Add a backend to the director with a certain weight.
- Weight is used as in the random director. Recommended value is
- 1.0 unless you have special needs.
+Weight is used as in the random director. Recommended value is 1.0
+unless you have special needs.
+
+Example::
-Example
vdir.add_backend(backend1, 1.0);
$Method VOID .remove_backend(BACKEND)
-Description
- Remove a backend from the director.
-Example
+Remove a backend from the director.
+
+Example::
vdir.remove_backend(backend1);
$Method BACKEND .backend(STRING_LIST)
-Description
- Pick a backend from the backend director.
+Pick a backend from the backend director.
- Use the string or list of strings provided to pick the backend.
-Example
- | # pick a backend based on the cookie header from the client
- | set req.backend_hint = vdir.backend(req.http.cookie);
+Use the string or list of strings provided to pick the backend.
+
+Example::
+ # pick a backend based on the cookie header from the client
+ set req.backend_hint = vdir.backend(req.http.cookie);
$Object shard()
Create a shard director.
Note that the shard director needs to be configured using at least one
-``shard.add_backend()`` call(s) **followed by a**
-``shard.reconfigure()`` **call** before it can hand out backends.
+`vmod_directors.shard.add_backend`_ call(s) **followed by a**
+`vmod_directors.shard.reconfigure`_ **call** before it can hand out
+backends.
_Note_ that due to various restrictions (documented below), it is
recommended to use the shard director on the backend side.
@@ -259,7 +269,7 @@ Varnish servers:
application servers, requesting similar objects from the same server
may help to optimize efficiency of such caches.
- For example, sharding by URL or some `id` component of the url has
+ For example, sharding by URL or some *id* component of the url has
been shown to drastically improve the efficiency of many content
management systems.
@@ -302,24 +312,24 @@ The drawbacks are:
Method
``````
-When ``.reconfigure()`` is called, a consistent hashing circular data
-structure gets built from the last 32 bits of SHA256 hash values of
-`<ident>`\ `<n>` (default `ident` being the backend name) for each
-backend and for a running number `n` from 1 to `replicas`. Hashing
-creates the seemingly random order for placement of backends on the
-consistent hashing ring.
+When `vmod_directors.shard.reconfigure`_ is called, a consistent
+hashing circular data structure gets built from the last 32 bits of
+SHA256 hash values of *<ident>*\ *<n>* (default *ident* being the
+backend name) for each backend and for a running number *n* from 1 to
+*replicas*. Hashing creates the seemingly random order for placement
+of backends on the consistent hashing ring.
-When ``.backend()`` is called, a load balancing key gets generated
-unless provided. The smallest hash value in the circle is looked up
-that is larger than the key (searching clockwise and wrapping around
-as necessary). The backend for this hash value is the preferred
-backend for the given key.
+When `vmod_directors.shard.backend`_ is called, a load balancing key
+gets generated unless provided. The smallest hash value in the circle
+is looked up that is larger than the key (searching clockwise and
+wrapping around as necessary). The backend for this hash value is the
+preferred backend for the given key.
If a healthy backend is requested, the search is continued linearly on
the ring as long as backends found are unhealthy or all backends have
-been checked. The order of these "alternative backends" on the ring
-is likely to differ for different keys. Alternative backends can also
-be selected explicitly.
+been checked. The order of these "alternative backends" on the ring is
+likely to differ for different keys. Alternative backends can also be
+selected explicitly.
On consistent hashing see:
@@ -338,61 +348,65 @@ when configuring the shard director, you are advised to check::
$Method VOID .set_warmup(REAL probability=0.0)
-Set the default warmup probability. See the `warmup` parameter of
-``shard.backend()``. If probability is 0.0 (default), warmup is
-disabled.
+Set the default warmup probability. See the *warmup* parameter of
+`vmod_directors.shard.backend`_. If *probability* is 0.0 (default),
+warmup is disabled.
$Method VOID .set_rampup(DURATION duration=0)
-Set the default rampup duration. See `rampup` parameter of
-`shard.backend()`. If duration is 0 (default), rampup is disabled.
+Set the default rampup duration. See *rampup* parameter of
+`vmod_directors.shard.backend`_. If *duration* is 0 (default), rampup
+is disabled.
$Method VOID .associate(BLOB param=0)
Associate a default `vmod_directors.shard_param`_ object or clear an
association.
-The value of the `param` argument must be a call to the
+The value of the *param* argument must be a call to the
`vmod_directors.shard_param.use`_ method. No argument clears the
association.
-The association can be changed per backend request using the `param`
+The association can be changed per backend request using the *param*
argument of `vmod_directors.shard.backend`_.
$Method BOOL .add_backend(PRIV_TASK, BACKEND backend,
[STRING ident], [DURATION rampup])
-Add a backend `backend` to the director.
+Add a backend *backend* to the director.
-`ident`: Optionally specify an identification string for this backend,
-which will be hashed by `shard.reconfigure()` to construct the
-consistent hashing ring. The identification string defaults to the
-backend name.
+*ident*: Optionally specify an identification string for this backend,
+which will be hashed by `vmod_directors.shard.reconfigure`_ to
+construct the consistent hashing ring. The identification string
+defaults to the backend name.
-`ident` allows to add multiple instances of the same backend.
+*ident* allows to add multiple instances of the same backend.
-`rampup`: Optionally specify a specific rampup time for this
+*rampup*: Optionally specify a specific rampup time for this
backend. Otherwise, the per-director rampup time is used (see
-:ref:`vmod_directors.shard.set_rampup`).
+`vmod_directors.shard.set_rampup`_).
-NOTE: Backend changes need to be finalized with `shard.reconfigure()`
-and are only supported on one shard director at a time.
+NOTE: Backend changes need to be finalized with
+`vmod_directors.shard.reconfigure`_ and are only supported on one
+shard director at a time.
$Method BOOL .remove_backend(PRIV_TASK, [BACKEND backend=0], [STRING ident=0])
-Remove backend(s) from the director. Either `backend` or `ident` must
-be specified. `ident` removes a specific instance. If `backend` is
-given without `ident`, all instances of this backend are removed.
+Remove backend(s) from the director. Either *backend* or *ident* must
+be specified. *ident* removes a specific instance. If *backend* is
+given without *ident*, all instances of this backend are removed.
-NOTE: Backend changes need to be finalized with `shard.reconfigure()`
-and are only supported on one shard director at a time.
+NOTE: Backend changes need to be finalized with
+`vmod_directors.shard.reconfigure`_ and are only supported on one
+shard director at a time.
$Method BOOL .clear(PRIV_TASK)
Remove all backends from the director.
-NOTE: Backend changes need to be finalized with `shard.reconfigure()`
-and are only supported on one shard director at a time.
+NOTE: Backend changes need to be finalized with
+`vmod_directors.shard.reconfigure`_ and are only supported on one
+shard director at a time.
$Method BOOL .reconfigure(PRIV_TASK, INT replicas=67)
@@ -403,13 +417,13 @@ used.
$Method INT .key(STRING_LIST)
-Convenience method to generate a sharding key for use with the `key`
-argument to the ``shard.backend()`` method by hashing the given string
-with SHA256.
+Convenience method to generate a sharding key for use with the *key*
+argument to the `vmod_directors.shard.backend`_ method by hashing the
+given string with SHA256.
To generate sharding keys using other hashes, use a custom vmod like
-`vmod blobdigest`_ with the `key_blob` argument of the
-``shard.backend()`` method.
+`vmod blobdigest`_ with the *key_blob* argument of the
+`vmod_directors.shard.backend`_ method.
.. _vmod blobdigest: https://code.uplex.de/uplex-varnish/libvmod-blobdigest/blob/master/README.rst
@@ -433,91 +447,91 @@ differ for different keys, depending on the number of backends and the
number of replicas. In particular, the backend order referred to here
is _not_ the order given when backends are added.
-* `by` how to determine the sharding key
+* *by* how to determine the sharding key
- * `HASH`:
+ * ``HASH``:
* when called in backend context: Use the varnish hash value as
- set by `vcl_hash`
+ set by ``vcl_hash{}``
- * when called in client context: hash `req.url`
+ * when called in client context: hash ``req.url``
- * `URL`: hash req.url / bereq.url
+ * ``URL``: hash req.url / bereq.url
- * `KEY`: use the `key` argument
+ * ``KEY``: use the *key* argument
- * `BLOB`: use the `key_blob` argument
+ * ``BLOB``: use the *key_blob* argument
-* `key` lookup key with `by=KEY`
+* *key* lookup key with ``by=KEY``
- the `shard.key()` function may come handy to generate a sharding
- key from custom strings.
+ the `vmod_directors.shard.key`_ method may come handy to generate a
+ sharding key from custom strings.
-* `key_blob` lookup key with `by=BLOB`
+* *key_blob* lookup key with ``by=BLOB``
Currently, this uses the first 4 bytes from the given blob in
network byte order (big endian), left-padded with zeros for blobs
smaller than 4 bytes.
-* `alt` alternative backend selection
+* *alt* alternative backend selection
- Select the `alt`-th alternative backend for the given `key`.
+ Select the *alt*-th alternative backend for the given *key*.
This is particularly useful for retries / restarts due to backend
- errors: By setting `alt=req.restarts` or `alt=bereq.retries` with
+ errors: By setting ``alt=req.restarts`` or ``alt=bereq.retries`` with
healthy=ALL, another server gets selected.
- The rampup and warmup features are only active for `alt==0`
+ The rampup and warmup features are only active for ``alt==0``
-* `rampup` slow start for servers which just went healthy
+* *rampup* slow start for servers which just went healthy
- If `alt==0` and the chosen backend is in its rampup period, with a
+ If ``alt==0`` and the chosen backend is in its rampup period, with a
probability proportional to the fraction of time since the backup
became healthy to the rampup period, return the next alternative
backend, unless this is also in its rampup period.
The default rampup interval can be set per shard director using the
- `set_rampup()` method or specifically per backend with the
- `set_backend()` method.
+ `vmod_directors.shard.set_rampup`_ method or specifically per
+ backend with the `vmod_directors.shard.add_backend`_ method.
-* `warmup` probabilistic alternative server selection
+* *warmup* probabilistic alternative server selection
possible values: -1, 0..1
- `-1`: use the warmup probability from the director definition
+ ``-1``: use the warmup probability from the director definition
- Only used for `alt==0`: Sets the ratio of requests (0.0 to 1.0) that
- goes to the next alternate backend to warm it up when the preferred
- backend is healthy. Not active if any of the preferred or
+ Only used for ``alt==0``: Sets the ratio of requests (0.0 to 1.0)
+ that goes to the next alternate backend to warm it up when the
+ preferred backend is healthy. Not active if any of the preferred or
alternative backend are in rampup.
- `warmup=0.5` is a convenient way to spread the load for each key
+ ``warmup=0.5`` is a convenient way to spread the load for each key
over two backends under normal operating conditions.
-* `healthy`
+* *healthy*
* CHOSEN: Return a healthy backend if possible.
- For `alt==0`, return the first healthy backend or none.
+ For ``alt==0``, return the first healthy backend or none.
- For `alt > 0`, ignore the health state of backends skipped for
+ For ``alt > 0``, ignore the health state of backends skipped for
alternative backend selection, then return the next healthy
backend. If this does not exist, return the last healthy backend
of those skipped or none.
* IGNORE: Completely ignore backend health state
- Just return the first or `alt`-th alternative backend, ignoring
- health state. Ignore `rampup` and `warmup`.
+ Just return the first or *alt*-th alternative backend, ignoring
+ health state, *rampup* and *warmup*.
* ALL: Check health state also for alternative backend selection
- For `alt > 0`, return the `alt`-th alternative backend of all
+ For ``alt > 0``, return the *alt*-th alternative backend of all
those healthy, the last healthy backend found or none.
-* `resolve`
+* *resolve*
- default: `LAZY` in ``vcl_init{}``, `NOW` otherwise
+ default: ``LAZY`` in ``vcl_init{}``, ``NOW`` otherwise
* ``NOW``: look up a backend and return it.
@@ -535,9 +549,9 @@ is _not_ the order given when backends are added.
parameter set affect the shard director instance for the backend
request irrespective of where it is referenced.
-* `param`
+* *param*
- Use or associate a parameter set. The value of the `param` argument
+ Use or associate a parameter set. The value of the *param* argument
must be a call to the `vmod_directors.shard_param.use`_ method.
default: as set by `vmod_directors.shard.associate`_ or unset.
@@ -545,25 +559,27 @@ is _not_ the order given when backends are added.
* for ``resolve=NOW`` take parameter defaults from the
`vmod_directors.shard_param`_ parameter set
- * for ``resolve=LAZY`` associate the `vmod_directors.shard_param`_ parameter
- set for this backend request
+ * for ``resolve=LAZY`` associate the `vmod_directors.shard_param`_
+ parameter set for this backend request
Implementation notes for use of parameter sets with
``resolve=LAZY``:
- * A `param` argument remains associated and any changes to the
+ * A *param* argument remains associated and any changes to the
associated parameter set affect the sharding decision once the
director resolves to an actual backend.
- * If other parameter arguments are also given, they have preference
- and are kept even if the parameter set given by the `param`
- argument is subsequently changed within the same backend request.
+ * If other parameter arguments are also given, they have
+ preference and are kept even if the parameter set given by the
+ *param* argument is subsequently changed within the same backend
+ request.
- * Each call to `vmod_directors.shard.backend`_ overrides any previous call.
+ * Each call to `vmod_directors.shard.backend`_ overrides any
+ previous call.
$Method VOID .debug(INT)
-`intentionally undocumented`
+*intentionally undocumented*
$Object shard_param()
@@ -592,18 +608,18 @@ implement retries on alternative backends::
sub vcl_init {
new shard_param = directors.shard_param();
-
+
new dir_A = directors.shard();
dir_A.add_backend(...);
dir_A.reconfigure(shard_param);
dir_A.associate(shard_param.use()); # <-- !
-
+
new dir_B = directors.shard();
dir_B.add_backend(...);
dir_B.reconfigure(shard_param);
dir_B.associate(shard_param.use()); # <-- !
}
-
+
sub vcl_recv {
if (...) {
set req.backend_hint = dir_A.backend(resolve=LAZY);
@@ -611,7 +627,7 @@ implement retries on alternative backends::
set req.backend_hint = dir_B.backend(resolve=LAZY);
}
}
-
+
sub vcl_backend_fetch {
# changes dir_A and dir_B behaviour
shard_param.set(alt=bereq.retries);
@@ -650,7 +666,7 @@ This method may not be used in client context
$Method STRING .get_by()
-Get a string representation of the `by` enum argument which denotes
+Get a string representation of the *by* enum argument which denotes
how a shard director using this parameter object would derive the
shard key. See `vmod_directors.shard.backend`_.
@@ -661,22 +677,22 @@ use. See `vmod_directors.shard.backend`_.
$Method INT .get_alt()
-Get the `alt` parameter which a shard director using this parameter
+Get the *alt* parameter which a shard director using this parameter
object would use. See `vmod_directors.shard.backend`_.
$Method REAL .get_warmup()
-Get the `warmup` parameter which a shard director using this parameter
+Get the *warmup* parameter which a shard director using this parameter
object would use. See `vmod_directors.shard.backend`_.
$Method BOOL .get_rampup()
-Get the `rampup` parameter which a shard director using this parameter
+Get the *rampup* parameter which a shard director using this parameter
object would use. See `vmod_directors.shard.backend`_.
$Method STRING .get_healthy()
-Get a string representation of the `healthy` enum argument which a
+Get a string representation of the *healthy* enum argument which a
shard director using this parameter object would use. See
`vmod_directors.shard.backend`_.
@@ -684,8 +700,8 @@ $Method BLOB .use()
This method may only be used in backend context.
-For use with the `param` argument of `vmod_directors.shard.backend`_ to associate
-this shard parameter set with a shard director.
+For use with the *param* argument of `vmod_directors.shard.backend`_
+to associate this shard parameter set with a shard director.
$Function BACKEND lookup(STRING)
diff --git a/lib/libvmod_proxy/vmod.vcc b/lib/libvmod_proxy/vmod.vcc
index 2d0663582..d07456cb5 100644
--- a/lib/libvmod_proxy/vmod.vcc
+++ b/lib/libvmod_proxy/vmod.vcc
@@ -31,91 +31,96 @@ $Module proxy 3 "Varnish Module to extract TLV attributes from PROXYv2"
DESCRIPTION
===========
-`vmod_proxy` contains functions to extract proxy-protocol-v2 TLV attributes
-as described in https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt.
-
+*vmod_proxy* contains functions to extract proxy-protocol-v2 TLV
+attributes as described in
+https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt.
$Function STRING alpn()
-Description
- Extract ALPN attribute.
-Example
+Extract ALPN attribute.
+
+Example::
+
set req.http.alpn = proxy.alpn();
$Function STRING authority()
-Description
- Extract authority attribute. This corresponds to SNI from a TLS
- connection.
-Example
+Extract authority attribute. This corresponds to SNI from a TLS
+connection.
+
+Example::
+
set req.http.authority = proxy.authority();
$Function BOOL is_ssl()
-Description
- Report if proxy-protocol-v2 has SSL TLV.
+Report if proxy-protocol-v2 has SSL TLV.
+
+Example::
-Example
- | if (proxy.is_ssl()) {
- | set req.http.ssl-version = proxy.ssl_version();
- | }
+ if (proxy.is_ssl()) {
+ set req.http.ssl-version = proxy.ssl_version();
+ }
$Function BOOL client_has_cert_sess()
-Description
- Report if the client provided a certificate at least once over the TLS
- session this connection belongs to.
+Report if the client provided a certificate at least once over the TLS
+session this connection belongs to.
$Function BOOL client_has_cert_conn()
-Description
- Report if the client provided a certificate over the current connection.
+Report if the client provided a certificate over the current
+connection.
$Function INT ssl_verify_result()
-Description
- Report the SSL_get_verify_result from a TLS session. It only matters
- if client_has_cert_sess() is true. Per default, value is set to 0
- (X509_V_OK).
+Report the SSL_get_verify_result from a TLS session. It only matters
+if client_has_cert_sess() is true. Per default, value is set to 0
+(X509_V_OK).
-Example
- | if (proxy.client_has_cert_sess() && proxy.ssl_verify_result() == 0) {
- | set req.http.ssl-verify = "ok";
- | }
+Example::
+
+ if (proxy.client_has_cert_sess() && proxy.ssl_verify_result() == 0) {
+ set req.http.ssl-verify = "ok";
+ }
$Function STRING ssl_version()
-Description
- Extract SSL version attribute.
-Example
+Extract SSL version attribute.
+
+Example::
+
set req.http.ssl-version = proxy.ssl_version();
$Function STRING client_cert_cn()
-Description
- Extract the common name attribute of the client certificate's.
-Example
+Extract the common name attribute of the client certificate's.
+
+Example::
set req.http.cert-cn = proxy.client_cert_cn();
$Function STRING ssl_cipher()
-Description
- Extract the SSL cipher attribute.
-Example
+Extract the SSL cipher attribute.
+
+Example::
+
set req.http.ssl-cipher = proxy.ssl_cipher();
$Function STRING cert_sign()
-Description
- Extract the certificate signature algorithm attribute.
-Example
+Extract the certificate signature algorithm attribute.
+
+Example::
+
set req.http.cert-sign = proxy.cert_sign();
$Function STRING cert_key()
-Description
- Extract the certificate key algorithm attribute.
-Example
+Extract the certificate key algorithm attribute.
+
+Example::
+
set req.http.cert-key = proxy.cert_key();
SEE ALSO
diff --git a/lib/libvmod_purge/vmod.vcc b/lib/libvmod_purge/vmod.vcc
index c8d8185cc..a0fafde83 100644
--- a/lib/libvmod_purge/vmod.vcc
+++ b/lib/libvmod_purge/vmod.vcc
@@ -31,10 +31,11 @@ $Module purge 3 "Varnish Purge Module"
DESCRIPTION
===========
-`vmod_purge` contains functions that offer a finer-grained control than the
-``purge`` transition in ``vcl_recv``. The functions can only be called from
-``vcl_hit`` or ``vcl_miss`` and they should in general be used in both to
-ensure that all variants of a same object are taken care of.
+*vmod_purge* contains functions that offer a finer-grained control
+than ``return(purge)`` from ``vcl_recv{}``. The functions can only be
+called from ``vcl_hit{}`` or ``vcl_miss{}`` and they should in general
+be used in both to ensure that all variants of a same object are taken
+care of.
EXAMPLE
=======
@@ -83,20 +84,23 @@ EXAMPLE
$Function INT hard()
-Description
- This is equivalent to ``return(purge)`` but explicitly called from
- ``vcl_hit`` and ``vcl_miss``. It returns the number of purged objects.
-Example
+This is equivalent to ``return(purge)`` but explicitly called from
+``vcl_hit{}`` and ``vcl_miss{}``. It returns the number of purged
+objects.
+
+Example::
+
set req.http.purged = purge.hard();
$Function INT soft(DURATION ttl = 0, DURATION grace = -1, DURATION keep = -1)
-Description
- Sets the TTL, grace and keep. By default, TTL is set to 0 with grace
- and keep periods left untouched. Setting a negative value for grace or
- keep periods leaves them untouched. Setting all three parameters to
- 0 is equivalent to a hard purge. It can only be called from ``vcl_hit``
- or ``vcl_miss``. It returns the number of soft-purged objects.
+Sets the *ttl*, *grace* and *keep*.
+
+By default, *ttl* is set to 0 with *grace* and *keep* periods left
+untouched. Setting a negative value for *grace* or *keep* periods
+leaves them untouched. Setting all three parameters to ``0`` is
+equivalent to a hard purge. It can only be called from ``vcl_hit{}``
+or ``vcl_miss{}``. It returns the number of soft-purged objects.
SEE ALSO
========
diff --git a/lib/libvmod_unix/vmod.vcc b/lib/libvmod_unix/vmod.vcc
index 38e48a7d3..0c1140872 100644
--- a/lib/libvmod_unix/vmod.vcc
+++ b/lib/libvmod_unix/vmod.vcc
@@ -48,15 +48,15 @@ Examples::
Obtaining the peer credentials is possible on a platform that supports
one of the following:
-* ``getpeereid(3)`` (such as FreeBSD and other BSD-derived systems)
+* `getpeereid(3)` (such as FreeBSD and other BSD-derived systems)
-* the socket option ``SO_PEERCRED`` for ``getsockopt(2)`` (Linux)
+* the socket option ``SO_PEERCRED`` for `getsockopt(2)` (Linux)
-* ``getpeerucred(3C)`` (SunOS and descendants)
+* `getpeerucred(3C)` (SunOS and descendants)
On SunOS and friends, the ``PRIV_PROC_INFO`` privilege set is added to
the Varnish child process while the VMOD is loaded, see
-``setppriv(2)``.
+`setppriv(2)`.
On most platforms, the value returned is the effective user or group
that was valid when the peer process initiated the connection.
@@ -82,32 +82,32 @@ ERRORS
All functions in this VMOD are subject to the following constraints:
-* None of them may be called in ``vcl_init`` or ``vcl_fini``. If one
- of them is called in ``vcl_init``, then the VCL program will fail to
- load, with an error message from the VMOD.
+* None of them may be called in ``vcl_init{}`` or ``vcl_fini{}``. If
+ one of them is called in ``vcl_init{}``, then the VCL program will
+ fail to load, with an error message from the VMOD.
* If called on a platform that is not supported, then VCL failure is
invoked. An error message is written to the log (with the
``VCL_Error`` tag), and for all VCL subroutines except for
- ``vcl_synth``, control is directed immediately to ``vcl_synth``,
+ ``vcl_synth{}``, control is directed immediately to ``vcl_synth{}``,
with the response status set to 503 and the reason string set to
"VCL failed".
- If the failure occurs during ``vcl_synth``, then ``vcl_synth`` is
- aborted, and the the response line "503 VCL failed" is sent.
+ If the failure occurs during ``vcl_synth{}``, then ``vcl_synth{}``
+ is aborted, and the the response line "503 VCL failed" is sent.
* If the current listener is not a Unix domain socket, or if the
attempt to read credentials fails, then a ``VCL_Error`` message is
- written to the log. The STRING functions (``vmod_user`` and
- ``vmod_group``) return NULL, while the INT functions (``vmod_uid``
- and ``vmod_gid``) return -1.
+ written to the log. The STRING functions (`vmod_unix.user`_ and
+ `vmod_unix.group`_) return ``NULL``, while the INT functions
+ (`vmod_unix.uid`_ and `vmod_unix.gid`_) return -1.
SEE ALSO
========
* :ref:`varnishd(1)`
* :ref:`vcl(7)`
-* ``getpeereid(3)``
-* ``getsockopt(2)``
-* ``getpeerucred(3C)``
-* ``setppriv(2)``
+* `getpeereid(3)`
+* `getsockopt(2)`
+* `getpeerucred(3C)`
+* `setppriv(2)`
More information about the varnish-commit
mailing list