filters/ext2/nbdkit-ext2-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-ext2-filter - read and write files inside ext2, ext3 or
   4 ext4 filesystems
   5
   6 =head1 SYNOPSIS
   7
   8  nbdkit --filter=ext2 file fs.img ext2file=/disks/disk.raw
   9
  10 =for paragraph
  11
  12  nbdkit --filter=ext2 --filter=partition file fs.img \
  13     partition=1 ext2file=exportname
  14
  15 =head1 DESCRIPTION
  16
  17 C<nbdkit-ext2-filter> is an nbdkit filter which can read and
  18 write files inside ext2, ext3 or ext4 filesystem images.
  19
  20 Suppose you have an ext2/3/4 filesystem image called F<fs.img>
  21 which contains inside itself a file called F<disk.raw>
  22 inside a directory on the filesystem called F</disks>, then
  23 you could serve that file over NBD using:
  24
  25  nbdkit --filter=ext2 file fs.img ext2file=/disks/disk.raw
  26
  27 Commonly disk images are partitioned.  In that case, you must select
  28 just the partition of a disk image that contains an ext2 filesystem,
  29 by using L<nbdkit-partition-filter(1)>:
  30
  31  nbdkit --filter=ext2 --filter=partition file fs.img \
  32     partition=1 ext2file=/disks/disk.raw
  33
  34 This filter can both read and write to the file inside the filesystem.
  35 Use the I<-r> flag to force a readonly connection, but note this does
  36 I<not> guarantee that no writes are made to the filesystem.  In
  37 particular we may have to replay the ext3 journal in order to open a
  38 filesystem even read-only.
  39
  40 The filter does I<not> support multiple parallel connections, because
  41 there is a risk of corrupting the filesystem (as if the filesystem was
  42 mounted by multiple machines).  If a second connection is made to
  43 nbdkit, it will block until the first connection closes.
  44
  45 The filter is implemented using the ext2fs library which is provided
  46 in most Linux distros, and also available as part of the e2fsprogs
  47 project.
  48
  49 L<nbdkit-guestfs-plugin(1)> is a more generic plugin which can read
  50 files from all kinds of different filesystem types, even if they are
  51 partitioned or use logical volumes.  It uses libguestfs instead of
  52 e2fsprogs.
  53
  54 =head1 PARAMETERS
  55
  56 =over 4
  57
  58 =item B<ext2file=>PATH
  59
  60 The full path of the file within the filesystem that will be exposed
  61 over NBD.  The path must be absolute (starts with C</>).
  62
  63 =item B<ext2file=exportname>
  64
  65 The plugin will expose the path within the filesystem chosen by the
  66 exportname passed by the client.  Note that this mode allows the
  67 client to deduce which files exist within the disk image, which may be
  68 a security risk in some situations.
  69
  70 At present, when using this mode, the server does not advertise any
  71 particular exports; however, you may use
  72 L<nbdkit-exportname-filter(1)> to perform that task.  Similarly, the
  73 underlying plugin must support the default export name, C<"">.
  74
  75 =back
  76
  77 =head1 FILES
  78
  79 =over 4
  80
  81 =item F<$filterdir/nbdkit-ext2-filter.so>
  82
  83 The filter.
  84
  85 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
  86
  87 =back
  88
  89 =head1 VERSION
  90
  91 C<nbdkit-ext2-filter> first appeared in nbdkit 1.18,
  92 replacing C<nbdkit-ext2-plugin> which was added in nbdkit 1.4
  93 and removed in nbdkit 1.22.
  94
  95 =head1 SEE ALSO
  96
  97 L<nbdkit(1)>,
  98 L<nbdkit-plugin(3)>,
  99 L<nbdkit-exportname-filter(1)>,
 100 L<nbdkit-partition-filter(1)>,
 101 L<nbdkit-guestfs-plugin(1)>,
 102 L<http://e2fsprogs.sourceforge.net/>,
 103 L<fuse2fs(1)>.
 104
 105 =head1 AUTHORS
 106
 107 Eric Blake
 108
 109 Richard W.M. Jones
 110
 111 =head1 COPYRIGHT
 112
 113 Copyright Red Hat