diff --git a/bin/varnishd/builtin.vcl b/bin/varnishd/builtin.vcl index 65fc37fa11..b3ea64c899 100644 --- a/bin/varnishd/builtin.vcl +++ b/bin/varnishd/builtin.vcl @@ -28,7 +28,25 @@ # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF # SUCH DAMAGE. # -# This is the builtin VCL code +# This file contains the builtin VCL code. +# +# All subroutines in this file can be overridden by user-provided VCL. +# +# There are two main patterns for overridable subroutines: +# +# 1. `vcl_builtin_*` subroutines: These wrap core Varnish logic. When you +# override these in user VCL, your code runs first, followed by the +# builtin VCL code (unless you `return()`). Note that calling +# `vcl_builtin_*` from your own `vcl_builtin_*` does not work (triggers +# recursion check). +# +# 2. `vcl_req_*`, `vcl_beresp_*`, etc. subroutines: These act as specific +# "hooks" within the default Varnish behavior. Overriding these allows +# you to modify a narrow aspect of behavior without reimplementing the +# entire parent `vcl_builtin_*` logic. +# +# Consult the Varnish documentation for details on each subroutine and +# its intended use. vcl 4.0; diff --git a/doc/sphinx/users-guide/vcl-built-in-code.rst b/doc/sphinx/users-guide/vcl-built-in-code.rst index 8e458d98cf..cab68751fe 100644 --- a/doc/sphinx/users-guide/vcl-built-in-code.rst +++ b/doc/sphinx/users-guide/vcl-built-in-code.rst @@ -174,9 +174,8 @@ code using:: Built-in VCL reference ---------------------- -A copy of the ``builtin.vcl`` file might be provided with your Varnish -installation but :ref:`varnishd(1)` is the reference to determine the code -that is appended to any loaded VCL. +A copy of the ``builtin.vcl`` file can be obtained by running +``varnishd -x builtin``. The VCL compilation happens in two passes: @@ -186,3 +185,30 @@ The VCL compilation happens in two passes: Any VCL subroutine present in the built-in VCL can be extended, in which case the loaded VCL code will be executed before the built-in code. + +Re-enabling pipe mode +~~~~~~~~~~~~~~~~~~~~~ + +As of Varnish 8.0, Varnish no longer pipes unknown HTTP methods by default. +Instead, it returns a 501 synthetic error. If you want to re-enable pipe +mode for a specific method, you can do so by adding the following to your +VCL: + +.. code-block:: vcl + + sub vcl_req_method { + if (req.method == "CUSTOM") { + return (pipe); + } + } + +You can also re-enable pipe mode for a specific request, for example for +WebSockets: + +.. code-block:: vcl + + sub vcl_recv { + if (req.http.upgrade == "websocket") { + return (pipe); + } + }