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

NAME

6       nbdkit-tar-filter - read and write files inside tar files without
7       unpacking
8

SYNOPSIS

10        nbdkit file FILENAME.tar --filter=tar tar-entry=PATH_INSIDE_TAR
11

EXAMPLES

13   Serve a single file inside a tarball
14        nbdkit file file.tar --filter=tar tar-entry=some/disk.img
15        guestfish --format=raw -a nbd://localhost
16
17   Opening a disk image inside an OVA file
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 (-r option).  The plugin
30       supports write access, but writing to the VMDK file in the tarball does
31       not change data checksums stored in other files (the "rhel.mf" file in
32       this example), and as these will become incorrect you probably won't be
33       able to open the file with another tool afterwards.
34
35   Open a disk image inside a remote tar file
36       You can use other plugins apart from nbdkit-file-plugin(1) to provide
37       the tar file.  For example if the tar file is located on a web server
38       use:
39
40        nbdkit -r curl https://example.com/file.tar \
41               --filter=tar tar-entry=disk.img
42
43   Open a compressed tar file (read-only)
44       This filter cannot handle compressed tar files itself, but you can
45       combine it with nbdkit-gzip-filter(1) or nbdkit-xz-filter(1):
46
47        nbdkit file filename.tar.gz \
48               --filter=tar tar-entry=disk.img --filter=gzip
49        nbdkit file filename.tar.xz \
50               --filter=tar tar-entry=disk.img --filter=xz
51

DESCRIPTION

53       "nbdkit-tar-filter" is a filter which can read and writes files inside
54       an uncompressed tar file without unpacking the tar file.
55
56       The tar file is provided by the underlying plugin.  You must tell the
57       filter which entry in the tar file you wish to read and write using the
58       "tar-entry" parameter.  "tar-entry" must exactly match the file name in
59       the tar index.  Use "tar tf filename.tar" to list the index of a tar
60       file.
61
62       This filter will not work directly on compressed tar files.  You have
63       to combine it with another filter as shown in the example above.
64
65       Use the nbdkit -r flag to open the file readonly.  This is the safest
66       option because it guarantees that the tar file will not be modified.
67       Without -r writes will modify the tar file.
68
69       The disk image cannot be resized.
70

PARAMETERS

72       [tar-entry=]PATH_INSIDE_TAR
73           The path of the file inside the tarball to serve.  This parameter
74           is required.  It must exactly match the name stored in the tarball,
75           so use "tar tf filename.tar"
76
77       tar=gtar
78       tar=/PATH/TO/GTAR
79           Specify the program name or full path of GNU tar, in case "tar" on
80           $PATH is not GNU tar.  This filter requires GNU tar and will not
81           normally work with other tar programs (eg. on FreeBSD).
82

FILES

84       $filterdir/nbdkit-tar-filter.so
85           The plugin.
86
87           Use "nbdkit --dump-config" to find the location of $filterdir.
88

VERSION

90       "nbdkit-tar-filter" first appeared in nbdkit 1.22.  It is derived from
91       "nbdkit-tar-plugin" which first appeared in nbdkit 1.2.
92

SEE ALSO

94       nbdkit(1), nbdkit-curl-plugin(1), nbdkit-file-plugin(1),
95       nbdkit-gzip-filter(1), nbdkit-offset-filter(1), nbdkit-plugin(3),
96       nbdkit-ssh-plugin(1), nbdkit-xz-filter(1), tar(1).
97

AUTHORS

99       Richard W.M. Jones.
100
101       Based on the virt-v2v OVA importer written by Tomáš Golembiovský.
102

COPYRIGHT

104       Copyright (C) 2017-2020 Red Hat Inc.
105

LICENSE

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