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

FreeBSD Manual Pages

  
 
  

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

NAME
       nbdkit-cow-filter - nbdkit copy-on-write	(COW) filter

SYNOPSIS
	nbdkit --filter=cow plugin [plugin-args...]

DESCRIPTION
       "nbdkit-cow-filter" is a	filter that makes a temporary writable copy on
       top of a	read-only plugin.  It can be used to enable writes for plugins
       which only implement read-only access.  Note that:

       o   Anything written is thrown away as soon as nbdkit exits.

       o   All connections to the nbdkit instance see the same view of the
	   disk.

	   This	is different from nbd-server(1)	where each connection sees its
	   own copy-on-write overlay and simply	disconnecting the client
	   throws that away.  It also allows us	to create diffs, see below.

       o   The plugin is opened	read-only (as if the -r	flag was passed), but
	   you should not pass the -r flag to nbdkit.

       o   Note	that the use of	this filter rounds the image size down to a
	   multiple of the caching granularity (4096), 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).

       Limitations of the filter include:

       o   The underlying file/device must not be resized.

       o   The underlying plugin must behave anormallya, meaning that it must
	   serve the same data to each client.

PARAMETERS
       cow-on-cache=true
	   Treat a client cache	request	as a shortcut for copying unmodified
	   data	from the plugin	to the overlay,	rather than the	default	of
	   passing cache requests on to	the plugin. This parameter defaults to
	   false (which	leaves the overlay as small as possible), but setting
	   it can be useful for	converting cache commands into a form of copy-
	   on-read behavior, in	addition to the	filter's normal	copy-on-write
	   semantics.

EXAMPLES
       Serve the file disk.img,	allowing writes, but do	not save any changes
       into the	file:

	nbdkit --filter=cow file disk.img

       nbdkit-xz-plugin(1) only	supports read access, but you can provide
       temporary write access by doing (although this does not save changes to
       the file):

	nbdkit --filter=cow xz disk.xz

CREATING A DIFF	WITH QEMU-IMG
       Although	nbdkit-cow-filter itself cannot	save the differences, it is
       possible	to do this using an obscure feature of qemu-img(1).  nbdkit
       must remain continuously	running	during the whole operation, otherwise
       all changes will	be lost.

       Run nbdkit:

	nbdkit --filter=cow file disk.img

       and then	connect	with a client and make whatever	changes	you need.  At
       the end,	disconnect the client.

       Run these "qemu-img" commands to	construct a qcow2 file containing the
       differences:

	qemu-img create	-f qcow2 -b nbd:localhost diff.qcow2
	qemu-img rebase	-b disk.img diff.qcow2

       diff.qcow2 now contains the differences between the base	(disk.img) and
       the changes stored in nbdkit-cow-filter.	 "nbdkit" can now be killed.

ENVIRONMENT VARIABLES
       "TMPDIR"
	   The copy-on-write changes are 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-cow-filter.so
	   The filter.

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

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

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

AUTHORS
       Eric Blake

       Richard W.M. Jones

COPYRIGHT
       Copyright (C) 2018 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-cow-filter(1)

NAME | SYNOPSIS | DESCRIPTION | PARAMETERS | EXAMPLES | CREATING A DIFF WITH QEMU-IMG | 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-cow-filter&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help