plugins/ext2/nbdkit-ext2-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-ext2-plugin - read and write files inside ext2, ext3 or
   4 ext4 filesystems
   5
   6 =head1 SYNOPSIS
   7
   8  nbdkit ext2 disk=fs.img file=/disks/disk.raw
   9
  10 =head1 DESCRIPTION
  11
  12 C<nbdkit-ext2-plugin> is an nbdkit plugin which can read and
  13 write files inside ext2, ext3 or ext4 filesystem images.
  14
  15 Suppose you have an ext2/3/4 filesystem image called F<fs.img>
  16 which contains inside itself a file called F<disk.raw>
  17 inside a directory on the filesystem called F</disks>, then
  18 you could serve that file over NBD using:
  19
  20  nbdkit ext2 disk=fs.img file=/disks/disk.raw
  21
  22 This plugin can both read and write to the file inside the filesystem.
  23 Use the I<-r> flag to force a readonly connection, but note this does
  24 I<not> guarantee that no writes are made to the filesystem.  In
  25 particular we may have to replay the ext3 journal in order to open a
  26 filesystem even read-only.
  27
  28 The plugin does I<not> support multiple parallel connections, because
  29 there is a risk of corrupting the filesystem (as if the filesystem was
  30 mounted by multiple machines).  If a second connection is made to
  31 nbdkit, it will block until the first connection closes.
  32
  33 The plugin is implemented using the ext2fs library which is provided
  34 in most Linux distros, and also available as part of the e2fsprogs
  35 project.
  36
  37 L<nbdkit-guestfs-plugin(1)> is a more generic plugin which can read
  38 files from all kinds of different filesystem types, even if they are
  39 partitioned or use logical volumes.  It uses libguestfs instead of
  40 e2fsprogs.
  41
  42 =head1 PARAMETERS
  43
  44 =over 4
  45
  46 =item B<disk=>FILENAME
  47
  48 The ext2, ext3 or ext4 filesystem, a file on the host.
  49
  50 You could also use a device name here if the filesystem is located on
  51 a device.  Be careful that the filesystem is not being accessed in
  52 parallel by another program and is not mounted, as that will almost
  53 certainly result in disk corruption in the filesystem.
  54
  55 The plugin expects a raw filesystem.  If the file/device is
  56 partitioned, use L<nbdkit-partition-filter(1)>.
  57
  58 =item B<file=>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 =back
  64
  65 =head1 FILES
  66
  67 =over 4
  68
  69 =item F<$plugindir/nbdkit-ext2-plugin.so>
  70
  71 The plugin.
  72
  73 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
  74
  75 =back
  76
  77 =head1 VERSION
  78
  79 C<nbdkit-ext2-plugin> first appeared in nbdkit 1.4.
  80
  81 =head1 SEE ALSO
  82
  83 L<nbdkit(1)>,
  84 L<nbdkit-plugin(3)>,
  85 L<nbdkit-partition-filter(1)>,
  86 L<nbdkit-guestfs-plugin(1)>,
  87 L<http://e2fsprogs.sourceforge.net/>,
  88 L<fuse2fs(1)>.
  89
  90 =head1 AUTHORS
  91
  92 Richard W.M. Jones
  93
  94 =head1 COPYRIGHT
  95
  96 Copyright (C) 2018 Red Hat Inc.