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       ·   Note that the use of this filter rounds the image size down to a
29           multiple of the caching granularity (4096), to ease the
30           implementation. If you need to round the image size up instead to
31           access the last few bytes, combine this filter with
32           nbdkit-truncate-filter(1).
33
34       Limitations of the filter include:
35
36       ·   The underlying file/device must not be resized.
37
38       ·   The underlying plugin must behave “normally”, meaning that it must
39           serve the same data to each client.
40

PARAMETERS

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

EXAMPLES

52       Serve the file disk.img, allowing writes, but do not save any changes
53       into the file:
54
55        nbdkit --filter=cow file disk.img
56
57       nbdkit-xz-filter(1) only supports read access, but you can provide
58       temporary write access by doing (although this does not save changes to
59       the file):
60
61        nbdkit --filter=cow --filter=xz file disk.xz
62

CREATING A DIFF WITH QEMU-IMG

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

ENVIRONMENT VARIABLES

86       "TMPDIR"
87           The copy-on-write changes are stored in a temporary file located in
88           /var/tmp by default.  You can override this location by setting the
89           "TMPDIR" environment variable before starting nbdkit.
90

FILES

92       $filterdir/nbdkit-cow-filter.so
93           The filter.
94
95           Use "nbdkit --dump-config" to find the location of $filterdir.
96

VERSION

98       "nbdkit-cow-filter" first appeared in nbdkit 1.2.
99

SEE ALSO

101       nbdkit(1), nbdkit-file-plugin(1), nbdkit-truncate-filter(1),
102       nbdkit-xz-filter(1), nbdkit-filter(3), qemu-img(1).
103

AUTHORS

105       Eric Blake
106
107       Richard W.M. Jones
108

COPYRIGHT

110       Copyright (C) 2018 Red Hat Inc.
111

LICENSE

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