[master] 5ec6f29a0 [doc] add some notes about storage selection

[Nils Goroll]

commit 5ec6f29a06e9ebe8311f39c9954fd1c7e9afeb1f
Author: Guillaume Quintard <guillaume.quintard at varnish-software.com>
Date:   Thu Feb 20 13:00:57 2025 -0800

    [doc] add some notes about storage selection

diff --git a/doc/sphinx/reference/varnishd.rst b/doc/sphinx/reference/varnishd.rst
index d93721cae..569edc541 100644
--- a/doc/sphinx/reference/varnishd.rst
+++ b/doc/sphinx/reference/varnishd.rst
@@ -350,6 +350,10 @@ The following hash algorithms are available:
 Storage Backend
 ---------------
 
+Multiple storage backend (when the cached and in-flight objects are held) can
+be defined, and VCL can pilot which store is used by setting the
+`beresp.storage` variable (see `man vcl-var` for more information).
+
 The argument format to define storage backends is:
 
 -s <[name]=kind[,options]>
diff --git a/doc/sphinx/reference/vcl_var.rst b/doc/sphinx/reference/vcl_var.rst
index 08d1e7966..b9ef20e0d 100644
--- a/doc/sphinx/reference/vcl_var.rst
+++ b/doc/sphinx/reference/vcl_var.rst
@@ -1328,7 +1328,10 @@ beresp.storage
 	Writable from: vcl_backend_response, vcl_backend_error
 
 
-	The storage backend to use to save this object.
+	The storage backend to use to save this object. If
+	none is set, Varnish will pick a storage backend in a
+	round-robin fashion, or the `Transient` backend if
+	the object is short-lived.
 
 beresp.storage_hint	``VCL <= 4.0``
 
diff --git a/doc/sphinx/users-guide/storage-backends.rst b/doc/sphinx/users-guide/storage-backends.rst
index 0030461d9..b1bbdb31c 100644
--- a/doc/sphinx/users-guide/storage-backends.rst
+++ b/doc/sphinx/users-guide/storage-backends.rst
@@ -28,7 +28,15 @@ Storage backends are also called stevedores.
 .. _vmods: https://www.varnish-cache.org/vmods
 
 Besides the built-in storage backends, separately distributed extensions exist,
-which can be found on the `vmods`_ page by searching for "stevedore".
+
+Storage Selection
+~~~~~~~~~~~~~~~~~
+
+By default, Varnish will store short-lived and passed objects in a storage
+called `Transient`, described below.
+
+For other objects, it will rotate between all the non-transient storages,
+unless the VCL variable `beresp.storage` is explicitly set.
 
 default
 ~~~~~~~