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

NAME

6       nbdkit-ext2-filter - read and write files inside ext2, ext3 or ext4
7       filesystems
8

SYNOPSIS

10        nbdkit --filter=ext2 file fs.img ext2file=/disks/disk.raw
11
12        nbdkit --filter=ext2 --filter=partition file fs.img \
13           partition=1 ext2file=exportname
14

DESCRIPTION

16       "nbdkit-ext2-filter" is an nbdkit filter which can read and write files
17       inside ext2, ext3 or ext4 filesystem images.
18
19       Suppose you have an ext2/3/4 filesystem image called fs.img which
20       contains inside itself a file called disk.raw inside a directory on the
21       filesystem called /disks, then you could serve that file over NBD
22       using:
23
24        nbdkit --filter=ext2 file fs.img ext2file=/disks/disk.raw
25
26       Commonly disk images are partitioned.  In that case, you must select
27       just the partition of a disk image that contains an ext2 filesystem, by
28       using nbdkit-partition-filter(1):
29
30        nbdkit --filter=ext2 --filter=partition file fs.img \
31           partition=1 ext2file=/disks/disk.raw
32
33       This filter can both read and write to the file inside the filesystem.
34       Use the -r flag to force a readonly connection, but note this does not
35       guarantee that no writes are made to the filesystem.  In particular we
36       may have to replay the ext3 journal in order to open a filesystem even
37       read-only.
38
39       The filter does not support multiple parallel connections, because
40       there is a risk of corrupting the filesystem (as if the filesystem was
41       mounted by multiple machines).  If a second connection is made to
42       nbdkit, it will block until the first connection closes.
43
44       The filter is implemented using the ext2fs library which is provided in
45       most Linux distros, and also available as part of the e2fsprogs
46       project.
47
48       nbdkit-guestfs-plugin(1) is a more generic plugin which can read files
49       from all kinds of different filesystem types, even if they are
50       partitioned or use logical volumes.  It uses libguestfs instead of
51       e2fsprogs.
52

PARAMETERS

54       ext2file=PATH
55           The full path of the file within the filesystem that will be
56           exposed over NBD.  The path must be absolute (starts with "/").
57
58       ext2file=exportname
59           The plugin will expose the path within the filesystem chosen by the
60           exportname passed by the client.  Note that this mode allows the
61           client to deduce which files exist within the disk image, which may
62           be a security risk in some situations.
63
64           At present, when using this mode, the server does not advertise any
65           particular exports; however, you may use
66           nbdkit-exportname-filter(1) to perform that task.  Similarly, the
67           underlying plugin must support the default export name, "".
68

FILES

70       $filterdir/nbdkit-ext2-filter.so
71           The filter.
72
73           Use "nbdkit --dump-config" to find the location of $filterdir.
74

VERSION

76       "nbdkit-ext2-filter" first appeared in nbdkit 1.18, replacing
77       "nbdkit-ext2-plugin" which was added in nbdkit 1.4 and removed in
78       nbdkit 1.22.
79

SEE ALSO

81       nbdkit(1), nbdkit-plugin(3), nbdkit-exportname-filter(1),
82       nbdkit-partition-filter(1), nbdkit-guestfs-plugin(1),
83       http://e2fsprogs.sourceforge.net/, fuse2fs(1).
84

AUTHORS

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

COPYRIGHT

91       Copyright (C) 2018-2020 Red Hat Inc.
92

LICENSE

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