Document resize operations

Closes #50

src/vmod_slash.man.rst

@@ -426,7 +426,8 @@ new xfellow = slash.fellow(STRING path, BYTES dsksize, BYTES memsize, BYTES objs
    )
 
 Create or reference a fellow storage on *path* of size *dsksize*
-with a memory cache of size *memsize*.
+with a memory cache of size *memsize*. See `slash_fellow_resize`_
+below for information on changing sizes.
 
 A VCL-defined fellow storage can not load persisted objects, so to
 avoid accidentally emptying a storage, either the storage referenced
@@ -477,6 +478,92 @@ will be used (which might fail of insufficient memory is available).
 
 *delete* specifies if the storage is to be emptied.
 
+.. _slash_fellow_resize:
+
+Resizing fellow storage
+~~~~~~~~~~~~~~~~~~~~~~~
+
+In general, resizing a fellow storage is supported by restarting
+varnishd with different parameters (be it on the command line or in
+VCL), but for size reductions, cache contents may be lost, to the
+extent of all cache contents. Read this paragraph for details:
+
+Increasing ``memsize``
+
+  Increasing ``memsize`` up to ``dsksize`` should never cause any
+  issues: Administrators should make sure that the amount of memory is
+  actually available (which might need additional consideration if huge
+  pages are used, see `INSTALL.rst`_), change the parameter and restart
+  :ref:`varnishd(1)`. Configuring ``memsize`` larger than ``dsksize`` is
+  not supported.
+
+Decreasing ``memsize``
+
+  When decreasing ``memsize``, first and foremost consider that
+  performance might significantly degrade, depending on access
+  patterns. As a simple rule, it is recommended to only reduce
+  ``memsize`` of an existing cache by halving at most and then letting
+  the cache contents rotate.
+
+  Consider that a dynamic minimum applies to ``memsize`` (see the
+  paragraph on *objsize_hint* in `slash.fellow()`_), so it can not be
+  made arbitrarily small. ``memsize`` also caps some tunables (see
+  `xfellow.tune()`_), of which *chunk_exponent* / *chunk_bytes*
+  deserve special consideration: At any time of fellow serving
+  requests for object bodies, some number of chunks needs to fit in
+  memory. Obviously, fellow can not work if a new ``memsize`` is
+  chosen too small to fit existing disk chunks. To be on the safe
+  side, *chunk_exponent* / *chunk_bytes* should thus be reduced to at
+  most 1 / 1024 of the planned ``memsize`` reduction *before* the
+  reduction is applied. Then, ideally, all of the cache contents
+  should be recreated. Keep in mind that smaller chunk sizes are
+  generally less efficient.
+
+Increasing ``dsksize``
+
+  Increasing ``dsksize`` is generally not an issue. Keep in mind that
+  memory required for metadata and the minimum ``memsize`` will also
+  increase (see `slash.fellow()`_). It is recommended to increase
+  ``dsksize`` in steps of at least 10% to ensure that free space can
+  be used to accommodate grown log regions (otherwise objects need to
+  be removed until enough contiguous space is available).
+
+  If the configured storage path points to a file, fellow will make an
+  attempt to change its size using :ref:`posix_fallocate(3)`. Success
+  and failure will be reported as ``fellow: ... grown to ...`` or
+  ``fellow: ... warning, fallocate failed ...``.
+
+  If the configured storage path points to a block device, the
+  administrator needs to ensure that it is at least as large as
+  ``dsksize``, or fellow will not start.
+
+  Once the storage is loaded, the log regions will be recreated to
+  accommodate the now higher number of objects possible to store.
+
+Decreasing ``dsksize``
+
+  Decreasing ``dsksize`` is also supported and fellow will make an
+  effort to load as many objects from the shrunken storage as
+  possible, but it will not move data. That is to say, objects
+  residing entirely within the shrunken storage region will be loaded,
+  and others will simply be ignored.
+
+  This also applies to the log: If log blocks reside outside the
+  shrunken storage, the respective objects will not be loaded. Log
+  regions are reported when fellow starts up, so it is possible to
+  configure a reduced ``dsksize`` preserving the log, but this is not
+  a well supported operation. Consider getting professional support if
+  you require help with such advanced reconfigurations on a regular
+  basis.
+
+  Once a shrunken storage is loaded, the log regions will also be
+  shrunk according to the now projected number of objects possible to
+  store.
+
+  The actual size change will be applied to files using
+  :ref:`posix_fallocate(3)` as with increases. The size of block
+  devices can not be changed by fellow.
+
 .. _xfellow.tune():
 
 STRING xfellow.tune([INT logbuffer_size], [DURATION logbuffer_flush_interval], [REAL log_rewrite_ratio], [INT chunk_exponent], [BYTES chunk_bytes], [INT wait_table_exponent], [INT lru_exponent], [INT dsk_reserve_chunks], [INT mem_reserve_chunks], [BYTES objsize_hint], [BYTES objsize_max], [INT cram], [INT readahead], [BYTES discard_immediate], [INT io_batch_min], [INT io_batch_max], [ENUM hash_obj], [ENUM hash_log], [ENUM ioerr_obj], [ENUM ioerr_log], [ENUM allocerr_obj], [ENUM allocerr_log])

src/vmod_slash.vcc

@@ -372,7 +372,8 @@ $Object fellow(STRING path, BYTES dsksize, BYTES memsize,
     BYTES objsize_hint=262144, BOOL delete=0)
 
 Create or reference a fellow storage on *path* of size *dsksize*
-with a memory cache of size *memsize*.
+with a memory cache of size *memsize*. See `slash_fellow_resize`_
+below for information on changing sizes.
 
 A VCL-defined fellow storage can not load persisted objects, so to
 avoid accidentally emptying a storage, either the storage referenced
@@ -423,29 +424,105 @@ will be used (which might fail of insufficient memory is available).
 
 *delete* specifies if the storage is to be emptied.
 
-$Method STRING .tune(
-	[ INT		logbuffer_size ],
-	[ DURATION	logbuffer_flush_interval ],
-	[ REAL		log_rewrite_ratio ],
-	[ INT		chunk_exponent ],
-	[ BYTES		chunk_bytes ],
-	[ INT		wait_table_exponent ],
-	[ INT		lru_exponent ],
-	[ INT		dsk_reserve_chunks ],
-	[ INT		mem_reserve_chunks ],
-	[ BYTES		objsize_hint ],
-	[ BYTES		objsize_max ],
-	[ INT		cram ],
-	[ INT		readahead ],
-	[ BYTES		discard_immediate ],
-	[ INT		io_batch_min ],
-	[ INT		io_batch_max ],
-	[ ENUM { sha256, xxh32, xxh3_64, xxh3_128 } hash_obj ],
-	[ ENUM { sha256, xxh32, xxh3_64, xxh3_128 } hash_log ],
-	[ ENUM { panic, purge } ioerr_obj ],
-	[ ENUM { panic, fail } ioerr_log ],
-	[ ENUM { panic, purge } allocerr_obj ],
-	[ ENUM { panic, fail } allocerr_log ])
+.. _slash_fellow_resize:
+
+Resizing fellow storage
+~~~~~~~~~~~~~~~~~~~~~~~
+
+In general, resizing a fellow storage is supported by restarting
+varnishd with different parameters (be it on the command line or in
+VCL), but for size reductions, cache contents may be lost, to the
+extent of all cache contents. Read this paragraph for details:
+
+Increasing ``memsize``
+
+  Increasing ``memsize`` up to ``dsksize`` should never cause any
+  issues: Administrators should make sure that the amount of memory is
+  actually available (which might need additional consideration if huge
+  pages are used, see `INSTALL.rst`_), change the parameter and restart
+  :ref:`varnishd(1)`. Configuring ``memsize`` larger than ``dsksize`` is
+  not supported.
+
+Decreasing ``memsize``
+
+  When decreasing ``memsize``, first and foremost consider that
+  performance might significantly degrade, depending on access
+  patterns. As a simple rule, it is recommended to only reduce
+  ``memsize`` of an existing cache by halving at most and then letting
+  the cache contents rotate.
+
+  Consider that a dynamic minimum applies to ``memsize`` (see the
+  paragraph on *objsize_hint* in `slash.fellow()`_), so it can not be
+  made arbitrarily small. ``memsize`` also caps some tunables (see
+  `xfellow.tune()`_), of which *chunk_exponent* / *chunk_bytes*
+  deserve special consideration: At any time of fellow serving
+  requests for object bodies, some number of chunks needs to fit in
+  memory. Obviously, fellow can not work if a new ``memsize`` is
+  chosen too small to fit existing disk chunks. To be on the safe
+  side, *chunk_exponent* / *chunk_bytes* should thus be reduced to at
+  most 1 / 1024 of the planned ``memsize`` reduction *before* the
+  reduction is applied. Then, ideally, all of the cache contents
+  should be recreated. Keep in mind that smaller chunk sizes are
+  generally less efficient.
+
+Increasing ``dsksize``
+
+  Increasing ``dsksize`` is generally not an issue. Keep in mind that
+  memory required for metadata and the minimum ``memsize`` will also
+  increase (see `slash.fellow()`_). It is recommended to increase
+  ``dsksize`` in steps of at least 10% to ensure that free space can
+  be used to accommodate grown log regions (otherwise objects need to
+  be removed until enough contiguous space is available).
+
+  If the configured storage path points to a file, fellow will make an
+  attempt to change its size using :ref:`posix_fallocate(3)`. Success
+  and failure will be reported as ``fellow: ... grown to ...`` or
+  ``fellow: ... warning, fallocate failed ...``.
+
+  If the configured storage path points to a block device, the
+  administrator needs to ensure that it is at least as large as
+  ``dsksize``, or fellow will not start.
+
+  Once the storage is loaded, the log regions will be recreated to
+  accommodate the now higher number of objects possible to store.
+
+Decreasing ``dsksize``
+
+  Decreasing ``dsksize`` is also supported and fellow will make an
+  effort to load as many objects from the shrunken storage as
+  possible, but it will not move data. That is to say, objects
+  residing entirely within the shrunken storage region will be loaded,
+  and others will simply be ignored.
+
+  This also applies to the log: If log blocks reside outside the
+  shrunken storage, the respective objects will not be loaded. Log
+  regions are reported when fellow starts up, so it is possible to
+  configure a reduced ``dsksize`` preserving the log, but this is not
+  a well supported operation. Consider getting professional support if
+  you require help with such advanced reconfigurations on a regular
+  basis.
+
+  Once a shrunken storage is loaded, the log regions will also be
+  shrunk according to the now projected number of objects possible to
+  store.
+
+  The actual size change will be applied to files using
+  :ref:`posix_fallocate(3)` as with increases. The size of block
+  devices can not be changed by fellow.
+
+
+$Method STRING .tune( [ INT logbuffer_size ], [ DURATION
+	logbuffer_flush_interval ], [ REAL log_rewrite_ratio ], [ INT
+	chunk_exponent ], [ BYTES chunk_bytes ], [ INT
+	wait_table_exponent ], [ INT lru_exponent ], [ INT
+	dsk_reserve_chunks ], [ INT mem_reserve_chunks ], [ BYTES
+	objsize_hint ], [ BYTES objsize_max ], [ INT cram ], [ INT
+	readahead ], [ BYTES discard_immediate ], [ INT io_batch_min
+	], [ INT io_batch_max ], [ ENUM { sha256, xxh32, xxh3_64,
+	xxh3_128 } hash_obj ], [ ENUM { sha256, xxh32, xxh3_64,
+	xxh3_128 } hash_log ], [ ENUM { panic, purge } ioerr_obj ], [
+	ENUM { panic, fail } ioerr_log ], [ ENUM { panic, purge }
+	allocerr_obj ], [ ENUM { panic, fail } allocerr_log ])
 
 Using the `xfellow.tune()`_ method, the following parameters of the
 fellow storage can be fine tuned: