1nbdkit-cow-filter(1)                NBDKIT                nbdkit-cow-filter(1)
2
3
4

NAME

6       nbdkit-cow-filter - nbdkit copy-on-write (COW) filter
7

SYNOPSIS

9        nbdkit --filter=cow plugin [plugin-args...]
10

DESCRIPTION

12       "nbdkit-cow-filter" is a filter that makes a temporary writable copy on
13       top of a read-only plugin.  It can be used to enable writes for plugins
14       which only implement read-only access.  Note that:
15
16       •   Anything written is thrown away as soon as nbdkit exits.
17
18       •   All connections to the nbdkit instance see the same view of the
19           disk.
20
21           This is different from nbd-server(1) where each connection sees its
22           own copy-on-write overlay and simply disconnecting the client
23           throws that away.  It also allows us to create diffs, see below.
24
25       •   The plugin is opened read-only (as if the -r flag was passed), but
26           you should not pass the -r flag to nbdkit.
27
28       Limitations of the filter include:
29
30       •   The underlying file/device must not be resized.
31
32       •   The underlying plugin must behave “normally”, meaning that it must
33           serve the same data to each client.
34

PARAMETERS

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

EXAMPLES

46       Serve the file disk.img, allowing writes, but do not save any changes
47       into the file:
48
49        nbdkit --filter=cow file disk.img
50
51       nbdkit-xz-filter(1) only supports read access, but you can provide
52       temporary write access by doing (although this does not save changes to
53       the file):
54
55        nbdkit --filter=cow --filter=xz file disk.xz
56

CREATING A DIFF WITH QEMU-IMG

58       Although nbdkit-cow-filter itself cannot save the differences, it is
59       possible to do this using an obscure feature of qemu-img(1).  nbdkit
60       must remain continuously running during the whole operation, otherwise
61       all changes will be lost.
62
63       Run nbdkit:
64
65        nbdkit --filter=cow file disk.img
66
67       and then connect with a client and make whatever changes you need.  At
68       the end, disconnect the client.
69
70       Run these "qemu-img" commands to construct a qcow2 file containing the
71       differences:
72
73        qemu-img create -f qcow2 -b nbd:localhost diff.qcow2
74        qemu-img rebase -b disk.img diff.qcow2
75
76       diff.qcow2 now contains the differences between the base (disk.img) and
77       the changes stored in nbdkit-cow-filter.  "nbdkit" can now be killed.
78

ENVIRONMENT VARIABLES

80       "TMPDIR"
81           The copy-on-write changes are stored in a temporary file located in
82           /var/tmp by default.  You can override this location by setting the
83           "TMPDIR" environment variable before starting nbdkit.
84

FILES

86       $filterdir/nbdkit-cow-filter.so
87           The filter.
88
89           Use "nbdkit --dump-config" to find the location of $filterdir.
90

VERSION

92       "nbdkit-cow-filter" first appeared in nbdkit 1.2.
93

SEE ALSO

95       nbdkit(1), nbdkit-file-plugin(1), nbdkit-xz-filter(1),
96       nbdkit-filter(3), qemu-img(1).
97

AUTHORS

99       Eric Blake
100
101       Richard W.M. Jones
102

104       Copyright (C) 2018-2021 Red Hat Inc.
105

LICENSE

107       Redistribution and use in source and binary forms, with or without
108       modification, are permitted provided that the following conditions are
109       met:
110
111       •   Redistributions of source code must retain the above copyright
112           notice, this list of conditions and the following disclaimer.
113
114       •   Redistributions in binary form must reproduce the above copyright
115           notice, this list of conditions and the following disclaimer in the
116           documentation and/or other materials provided with the
117           distribution.
118
119       •   Neither the name of Red Hat nor the names of its contributors may
120           be used to endorse or promote products derived from this software
121           without specific prior written permission.
122
123       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
124       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
125       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
126       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
127       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
128       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
129       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
130       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
131       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
132       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
133       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
134
135
136
137nbdkit-1.25.8                     2021-05-25              nbdkit-cow-filter(1)
Impressum