filters/tar/nbdkit-tar-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-tar-filter - read and write files inside tar files without unpacking
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit file FILENAME.tar --filter=tar tar-entry=PATH_INSIDE_TAR
   8
   9 =head1 EXAMPLES
  10
  11 =head2 Serve a single file inside a tarball
  12
  13  nbdkit file file.tar --filter=tar tar-entry=some/disk.img
  14  guestfish --format=raw -a nbd://localhost
  15
  16 =head2 Opening a disk image inside an OVA file
  17
  18 The popular "Open Virtual Appliance" (OVA) format is really an
  19 uncompressed tar file containing (usually) VMDK-format files, so you
  20 could access one file in an OVA like this:
  21
  22  $ tar tf rhel.ova
  23  rhel.ovf
  24  rhel-disk1.vmdk
  25  rhel.mf
  26  $ nbdkit -r file rhel.ova --filter=tar tar-entry=rhel-disk1.vmdk
  27  $ guestfish --ro --format=vmdk -a nbd://localhost
  28
  29 In this case the tarball is opened readonly (I<-r> option).  The
  30 plugin supports write access, but writing to the VMDK file in the
  31 tarball does not change data checksums stored in other files (the
  32 C<rhel.mf> file in this example), and as these will become incorrect
  33 you probably won't be able to open the file with another tool
  34 afterwards.
  35
  36 =head2 Open a disk image inside a remote tar file
  37
  38 You can use other plugins apart from L<nbdkit-file-plugin(1)> to
  39 provide the tar file.  For example if the tar file is located on a web
  40 server use:
  41
  42  nbdkit -r curl https://example.com/file.tar \
  43         --filter=tar tar-entry=disk.img
  44
  45 =head2 Open a compressed tar file (read-only)
  46
  47 This filter cannot handle compressed tar files itself, but you can
  48 combine it with L<nbdkit-gzip-filter(1)> or L<nbdkit-xz-filter(1)>:
  49
  50  nbdkit file filename.tar.gz \
  51         --filter=tar tar-entry=disk.img --filter=gzip
  52  nbdkit file filename.tar.xz \
  53         --filter=tar tar-entry=disk.img --filter=xz
  54
  55 =head1 DESCRIPTION
  56
  57 C<nbdkit-tar-filter> is a filter which can read and writes files
  58 inside an uncompressed tar file without unpacking the tar file.
  59
  60 The tar file is provided by the underlying plugin.  You must tell the
  61 filter which entry in the tar file you wish to read and write using
  62 the C<tar-entry> parameter.  C<tar-entry> must exactly match the file
  63 name in the tar index.  Use C<tar tf filename.tar> to list the index
  64 of a tar file.
  65
  66 This filter will B<not> work directly on compressed tar files.  You
  67 have to combine it with another filter as shown in the example above.
  68
  69 Use the nbdkit I<-r> flag to open the file readonly.  This is the
  70 safest option because it guarantees that the tar file will not be
  71 modified.  Without I<-r> writes will modify the tar file.
  72
  73 The disk image cannot be resized.
  74
  75 =head1 PARAMETERS
  76
  77 =over 4
  78
  79 =item [B<tar-entry=>]PATH_INSIDE_TAR
  80
  81 The path of the file inside the tarball to serve.  This parameter is
  82 required.  It must exactly match the name stored in the tarball, so
  83 use S<C<tar tf filename.tar>>
  84
  85 =item B<tar=gtar>
  86
  87 =item B<tar=>/PATH/TO/GTAR
  88
  89 Specify the program name or full path of GNU tar, in case C<tar> on
  90 C<$PATH> is not GNU tar.  This filter requires GNU tar and will not
  91 normally work with other tar programs (eg. on FreeBSD).
  92
  93 =back
  94
  95 =head1 FILES
  96
  97 =over 4
  98
  99 =item F<$filterdir/nbdkit-tar-filter.so>
 100
 101 The plugin.
 102
 103 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 104
 105 =back
 106
 107 =head1 VERSION
 108
 109 C<nbdkit-tar-filter> first appeared in nbdkit 1.22.  It is derived
 110 from C<nbdkit-tar-plugin> which first appeared in nbdkit 1.2.
 111
 112 =head1 SEE ALSO
 113
 114 L<nbdkit(1)>,
 115 L<nbdkit-curl-plugin(1)>,
 116 L<nbdkit-file-plugin(1)>,
 117 L<nbdkit-gzip-filter(1)>,
 118 L<nbdkit-offset-filter(1)>,
 119 L<nbdkit-plugin(3)>,
 120 L<nbdkit-ssh-plugin(1)>,
 121 L<nbdkit-xz-filter(1)>,
 122 L<tar(1)>.
 123
 124 =head1 AUTHORS
 125
 126 Richard W.M. Jones.
 127
 128 Based on the virt-v2v OVA importer written by Tomáš Golembiovský.
 129
 130 =head1 COPYRIGHT
 131
 132 Copyright Red Hat