Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
nbdkit-cache-filter(1)		    NBDKIT		nbdkit-cache-filter(1)

NAME
       nbdkit-cache-filter - nbdkit caching filter

SYNOPSIS
	nbdkit --filter=cache plugin [cache=writeback|writethrough|unsafe]
				     [cache-max-size=SIZE]
				     [cache-high-threshold=N]
				     [cache-low-threshold=N]
				     [cache-on-read=true|false]
				     [plugin-args...]

DESCRIPTION
       "nbdkit-cache-filter" is	a filter that adds caching on top of a plugin.
       This is useful if a plugin is slow or expensive to use, because nbdkit
       will try	to minimize requests to	the plugin by caching previous
       requests.

       Note that many NBD clients are able to do caching, and because the
       caching happens on the client side it will usually be more effective
       than caching inside the server.	This filter can	be used	if the client
       does not	have effective caching,	or (with "cache=unsafe") to defeat
       flush requests from the client (which is	unsafe and can cause data
       loss, as	the name suggests).

       Note that the use of this filter	rounds the image size down to a
       multiple	of the caching granularity (the	larger of 4096 or the
       "f_bsize" field of fstatvfs(3)),	to ease	the implementation. If you
       need to round the image size up instead to access the last few bytes,
       combine this filter with	nbdkit-truncate-filter(1).

       This filter only	caches image contents.	To cache image metadata, use
       nbdkit-cacheextents-filter(1) between this filter and the plugin.  To
       accelerate sequential reads, use	nbdkit-readahead-filter(1) instead.

PARAMETERS
       cache=writeback
	   Store writes	in the cache.  They are	not written to the plugin
	   unless an explicit flush is done by the client.

	   This	is the default caching mode, and is safe if your client	issues
	   flush requests correctly (which is true for modern Linux and	other
	   well-written	NBD clients).

       cache=writethrough
	   Always force	writes through to the plugin.

	   This	makes the cache	less effective,	but is necessary if your
	   client does not issue correct flush requests.

       cache=unsafe
	   Ignore flush	requests.  Never write to the plugin unless the	cache
	   grows too large.

	   This	is dangerous and can cause data	loss, but this may be
	   acceptable if you only use it for testing or	with data that you
	   don't care about or can cheaply reconstruct.

       cache-max-size=SIZE
       cache-high-threshold=N
       cache-low-threshold=N
	   Limit the size of the cache to "SIZE".  See "CACHE MAXIMUM SIZE"
	   below.

       cache-on-read=true
	   Cache read requests as well as write	and cache requests.  Any time
	   a block is read from	the plugin, it is saved	in the cache (if there
	   is sufficient space)	so the same data can be	served more quickly
	   later.

	   Note	that if	the underlying data served by the plugin can be
	   modified by some other means	(eg. something else can	write to a
	   file	which is being served by nbdkit-file-plugin(1)), this option
	   will	cause nbdkit to	serve stale data because reads won't always go
	   through to the plugin.

       cache-on-read=false
	   Do not cache	read requests (this is the default).

CACHE MAXIMUM SIZE
       By default the cache can	grow to	any size (although not larger than the
       virtual size of the underlying plugin) and you have to ensure there is
       sufficient space	in $TMPDIR for it.

       Using the parameters "cache-max-size", "cache-high-threshold" and
       "cache-low-threshold" you can limit the maximum size of the cache.

       This requires kernel and	filesystem support (for	fallocate(2)
       "FALLOC_FL_PUNCH_HOLE"),	so it may not work on all platforms.

       Some examples:

       "cache-max-size=1G"
	   The cache is	limited	to around 1 gigabyte.

       "cache-max-size=1G cache-high-threshold=95 cache-low-threshold=80"
	   Once	the cache size reaches 972M (95% of 1G), blocks	are reclaimed
	   from	the cache until	the size is reduced to 819M (80% of 1G).

       The way this works is once the size of the cache	exceeds
       "SIZE"A aA theA highA threshold,	the filter works to reduce the size of
       the cache until it is less than "SIZE"A aA theA lowA threshold.	Once
       the size	is below the low threshold, no more reclaim work is done until
       the size	exceeds	the high threshold again.

       The default thresholds are high 95% and low 80%.	 You must set
       0A <A lowA <A high.  The	thresholds are expressed as integer
       percentages of "cache-max-size".

       Least recently used blocks are discarded	first.

ENVIRONMENT VARIABLES
       "TMPDIR"
	   The cache is	stored in a temporary file located in /var/tmp by
	   default.  You can override this location by setting the "TMPDIR"
	   environment variable	before starting	nbdkit.

FILES
       $filterdir/nbdkit-cache-filter.so
	   The filter.

	   Use "nbdkit --dump-config" to find the location of $filterdir.

VERSION
       "nbdkit-cache-filter" first appeared in nbdkit 1.2.

SEE ALSO
       nbdkit(1), nbdkit-file-plugin(1), nbdkit-cacheextents-filter(1),
       nbdkit-readahead-filter(1), nbdkit-truncate-filter(1),
       nbdkit-filter(3), qemu-img(1).

AUTHORS
       Eric Blake

       Richard W.M. Jones

COPYRIGHT
       Copyright (C) 2018-2020 Red Hat Inc.

LICENSE
       Redistribution and use in source	and binary forms, with or without
       modification, are permitted provided that the following conditions are
       met:

       o   Redistributions of source code must retain the above	copyright
	   notice, this	list of	conditions and the following disclaimer.

       o   Redistributions in binary form must reproduce the above copyright
	   notice, this	list of	conditions and the following disclaimer	in the
	   documentation and/or	other materials	provided with the
	   distribution.

       o   Neither the name of Red Hat nor the names of	its contributors may
	   be used to endorse or promote products derived from this software
	   without specific prior written permission.

       THIS SOFTWARE IS	PROVIDED BY RED	HAT AND	CONTRIBUTORS ''AS IS'' AND ANY
       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
       LIABLE FOR ANY DIRECT, INDIRECT,	INCIDENTAL, SPECIAL, EXEMPLARY,	OR
       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
       SUBSTITUTE GOODS	OR SERVICES; LOSS OF USE, DATA,	OR PROFITS; OR
       BUSINESS	INTERRUPTION) HOWEVER CAUSED AND ON ANY	THEORY OF LIABILITY,
       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
       OTHERWISE) ARISING IN ANY WAY OUT OF THE	USE OF THIS SOFTWARE, EVEN IF
       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nbdkit-1.20.4			  2021-09-21		nbdkit-cache-filter(1)

NAME | SYNOPSIS | DESCRIPTION | PARAMETERS | CACHE MAXIMUM SIZE | ENVIRONMENT VARIABLES | FILES | VERSION | SEE ALSO | AUTHORS | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=nbdkit-cache-filter&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help