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       There are no parameters specific to nbdkit-cow-filter.  Any parameters
37       are passed through to and processed by the underlying plugin in the
38       normal way.
39

EXAMPLES

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

CREATING A DIFF WITH QEMU-IMG

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

ENVIRONMENT VARIABLES

75       "TMPDIR"
76           The copy-on-write changes are stored in a temporary file located in
77           /var/tmp by default.  You can override this location by setting the
78           "TMPDIR" environment variable before starting nbdkit.
79

SEE ALSO

81       nbdkit(1), nbdkit-file-plugin(1), nbdkit-xz-plugin(1),
82       nbdkit-filter(3), qemu-img(1).
83

AUTHORS

85       Eric Blake
86
87       Richard W.M. Jones
88

90       Copyright (C) 2018 Red Hat Inc.
91

LICENSE

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