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                                              [tar=TAR_COMMAND]
12

EXAMPLES

14   Serve a single file inside a tarball
15        nbdkit file file.tar --filter=tar tar-entry=some/disk.img
16        guestfish --format=raw -a nbd://localhost
17
18   Opening a disk image inside an OVA file
19       The popular "Open Virtual Appliance" (OVA) format is really an
20       uncompressed tar file containing (usually) VMDK-format files, so you
21       could access one file in an OVA like this:
22
23        $ tar tf rhel.ova
24        rhel.ovf
25        rhel-disk1.vmdk
26        rhel.mf
27        $ nbdkit -r file rhel.ova --filter=tar tar-entry=rhel-disk1.vmdk
28        $ guestfish --ro --format=vmdk -a nbd://localhost
29
30       In this case the tarball is opened readonly (-r option).  The plugin
31       supports write access, but writing to the VMDK file in the tarball does
32       not change data checksums stored in other files (the "rhel.mf" file in
33       this example), and as these will become incorrect you probably won't be
34       able to open the file with another tool afterwards.
35
36   Open a disk image inside a remote tar file
37       You can use other plugins apart from nbdkit-file-plugin(1) to provide
38       the tar file.  For example if the tar file is located on a web server
39       use:
40
41        nbdkit -r curl https://example.com/file.tar \
42               --filter=tar tar-entry=disk.img
43
44   Open a compressed tar file (read-only)
45       This filter cannot handle compressed tar files itself, but you can
46       combine it with nbdkit-gzip-filter(1) or nbdkit-xz-filter(1):
47
48        nbdkit file filename.tar.gz \
49               --filter=tar tar-entry=disk.img --filter=gzip
50        nbdkit file filename.tar.xz \
51               --filter=tar tar-entry=disk.img --filter=xz
52

DESCRIPTION

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

PARAMETERS

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

FILES

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

VERSION

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

SEE ALSO

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

AUTHORS

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

COPYRIGHT

105       Copyright Red Hat
106

LICENSE

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