Mailing List Archive

commit 490553b006251ca2c421d150eed3f50bbe8b9cfc
Author: Dridi Boukelmoune <dridi.boukelmoune@gmail.com>
Date: Thu Jan 25 16:00:00 2024 +0100

doc: Succinctly describe parameters units

This takes care of documenting the meaning of a zero timeout value in
a central location, since none of the timeout parameters have a mention
for the effect it produces.

This is written as if there was a separate varnish-param(7) manual,
which should eventually be enacted. This manual extraction was initially
implemented in the adjacent #3817 timeout nomenclature draft.

diff --git a/doc/sphinx/reference/varnishd.rst b/doc/sphinx/reference/varnishd.rst
index 16aa63260..002de7d73 100644
--- a/doc/sphinx/reference/varnishd.rst
+++ b/doc/sphinx/reference/varnishd.rst
@@ -540,6 +540,59 @@ to load the configurations at startup.
RUN TIME PARAMETERS
===================

+Runtime parameters can either be set during startup with the ``-p`` command
+line option for ``varnishd(1)`` or through the CLI using the ``param.set`` or
+``param.reset`` commands. They can be locked during startup with the ``-r``
+command line option.
+
+Run Time Parameter Units
+------------------------
+
+There are different types of parameters that may accept a list of specific
+values, or optionally take a unit suffix.
+
+bool
+~~~~
+
+A boolean parameter accepts the values ``on`` and ``off``.
+
+It will also recognize the following values:
+
+- ``yes`` and ``no``
+- ``true`` and ``false``
+- ``enable`` and ``disable``
+
+bytes
+~~~~~
+
+A bytes parameter requires one of the following units suffixes:
+
+- ``b`` (bytes)
+- ``k`` (kibibytes, 1024 bytes)
+- ``m`` (mebibytes, 1024 kibibytes)
+- ``g`` (gibibytes, 1024 mebibytes)
+- ``t`` (tebibytes, 1024 gibibytes)
+- ``p`` (pebibytes, 1024 tebibytes)
+
+Multiplicator units may be appended with an extra ``b``. For example ``32k``
+is equivalent to ``32kb``. Bytes units are case-insensitive.
+
+seconds
+~~~~~~~
+
+A duration parameter may accept the following units suffixes:
+
+- ``ms`` (milliseconds)
+- ``s`` (seconds)
+- ``m`` (minutes)
+- ``h`` (hours)
+- ``d`` (days)
+- ``w`` (weeks)
+- ``y`` (years)
+
+If the parameter is a timeout or a deadline, a value of zero (when allowed)
+disables the effect of the parameter.
+
Run Time Parameter Flags
------------------------

_______________________________________________
varnish-commit mailing list
varnish-commit@varnish-cache.org
https://www.varnish-cache.org/lists/mailman/listinfo/varnish-commit