1nbdkit-tar-filter(1) NBDKIT nbdkit-tar-filter(1)
2
6 nbdkit-tar-filter - read and write files inside tar files without
7 unpacking
8
10 nbdkit file FILENAME.tar
11 --filter=tar tar-entry=PATH_INSIDE_TAR
12 [tar=TAR_COMMAND] [tar-limit=SIZE]
13
15 Serve a single file inside a tarball
16 nbdkit file file.tar --filter=tar tar-entry=some/disk.img
17 guestfish --format=raw -a nbd://localhost
18 Opening a disk image inside an OVA file
20 The popular "Open Virtual Appliance" (OVA) format is really an
21 uncompressed tar file containing (usually) VMDK-format files, so you
22 could access one file in an OVA like this:
23 $ tar tf rhel.ova
25 rhel.ovf
26 rhel-disk1.vmdk
27 rhel.mf
28 $ nbdkit -r file rhel.ova --filter=tar tar-entry=rhel-disk1.vmdk
29 $ guestfish --ro --format=vmdk -a nbd://localhost
30 In this case the tarball is opened readonly (-r option). The plugin
32 supports write access, but writing to the VMDK file in the tarball does
33 not change data checksums stored in other files (the "rhel.mf" file in
34 this example), and as these will become incorrect you probably won't be
35 able to open the file with another tool afterwards.
36 Open a disk image inside a remote tar file
38 You can use other plugins apart from nbdkit-file-plugin(1) to provide
39 the tar file. For example if the tar file is located on a web server
40 use:
41 nbdkit -r curl https://example.com/file.tar \
43 --filter=tar tar-entry=disk.img
44 Open a compressed tar file (read-only)
46 This filter cannot handle compressed tar files itself, but you can
47 combine it with nbdkit-gzip-filter(1) or nbdkit-xz-filter(1):
48 nbdkit file filename.tar.gz \
50 --filter=tar tar-entry=disk.img --filter=gzip
51 nbdkit file filename.tar.xz \
52 --filter=tar tar-entry=disk.img --filter=xz
53
55 "nbdkit-tar-filter" is a filter which can read and writes files inside
56 an uncompressed tar file without unpacking the tar file.
57 The tar file is provided by the underlying plugin. You must tell the
59 filter which entry in the tar file you wish to read and write using the
60 "tar-entry" parameter. "tar-entry" must exactly match the file name in
61 the tar index. Use "tar tf filename.tar" to list the index of a tar
62 file.
63 This filter will not work directly on compressed tar files. You have
65 to combine it with another filter as shown in the example above.
66 Use the nbdkit -r flag to open the file readonly. This is the safest
68 option because it guarantees that the tar file will not be modified.
69 Without -r writes will modify the tar file.
70 The disk image cannot be resized.
72
74 [tar-entry=]PATH_INSIDE_TAR
75 The path of the file inside the tarball to serve. This parameter
76 is required. It must exactly match the name stored in the tarball,
77 so use "tar tf filename.tar"
78 [tar-limit=]SIZE
80 When opening the tar file we have to locate the file ("tar-entry")
81 inside the tarball. Because tar files do not have a central index
82 we must iterate over the tar file to find the entry, and that may
83 be costly (especially with untrusted tar files). In the worst case
84 where "tar-entry" starts near the end of the file we may have to
85 iterate over the whole tar file. If this is a problem you may set
86 "tar-limit" to some smaller value, eg:
87 nbdkit -r curl https://example.com/file.tar \
89 --filter=tar tar-entry=disk.img \
90 tar-limit=10M
91 which ensures no more than 10 megabytes are read before we give up
93 and reject the tar file (sending an error back to the NBD client).
94 The default is 0 meaning no limit.
96 tar=gtar
98 tar=/PATH/TO/GTAR
99 Specify the program name or full path of GNU tar, in case "tar" on
100 $PATH is not GNU tar. This filter requires GNU tar and will not
101 normally work with other tar programs (eg. on FreeBSD).
102
104 $filterdir/nbdkit-tar-filter.so
105 The plugin.
106 Use "nbdkit --dump-config" to find the location of $filterdir.
108
110 "nbdkit-tar-filter" first appeared in nbdkit 1.22. It is derived from
111 "nbdkit-tar-plugin" which first appeared in nbdkit 1.2.
112
114 nbdkit(1), nbdkit-curl-plugin(1), nbdkit-file-plugin(1),
115 nbdkit-gzip-filter(1), nbdkit-offset-filter(1), nbdkit-plugin(3),
116 nbdkit-ssh-plugin(1), nbdkit-xz-filter(1), tar(1).
117
119 Richard W.M. Jones.
120 Based on the virt-v2v OVA importer written by Tomáš Golembiovský.
122
124 Copyright Red Hat
125
127 Redistribution and use in source and binary forms, with or without
128 modification, are permitted provided that the following conditions are
129 met:
130 • Redistributions of source code must retain the above copyright
132 notice, this list of conditions and the following disclaimer.
133 • Redistributions in binary form must reproduce the above copyright
135 notice, this list of conditions and the following disclaimer in the
136 documentation and/or other materials provided with the
137 distribution.
138 • Neither the name of Red Hat nor the names of its contributors may
140 be used to endorse or promote products derived from this software
141 without specific prior written permission.
142 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
144 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
145 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
146 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
147 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
148 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
149 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
150 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
151 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
152 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
153 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
154nbdkit-1.36.2 2023-11-26 nbdkit-tar-filter(1)